Blog posts by Bartosz Sekula

Side by side editing - stable release

Tue, 10 Jun 2025 00:00:00 GMT

Combining the All Properties Mode with a Live Preview Stable Release

Side by side editing - alternative to Optimizely On-Page Edit

Thu, 09 Jan 2025 00:00:00 GMT

Combining the All Properties Mode with a self-updating preview in the Optimizely CMS

How to add an Admin Mode add-on in Optimizely CMS12

Thu, 02 Jan 2025 00:00:00 GMT

How to add a new add-on with navigation and unified stylesheet

Useful Optimizely CMS Web Components

Wed, 18 Dec 2024 00:00:00 GMT

A list of useful Optimizely CMS components that can be used in add-ons.

CMS + CMP + Graph integration

Tue, 05 Nov 2024 12:30:42 GMT

We have just released a new package https://nuget.optimizely.com/package/?id=EPiServer.Cms.WelcomeIntegration.Graph which changes the way CMS fetches CMP Asset metadata.

If you use the CMP it means that you also have access to Graph and can fetch metadata from it instead of relying on the CMP API.

There are a few steps required in order to start using the new package https://nuget.optimizely.com/package/?id=EPiServer.Cms.WelcomeIntegration.Graph

Existing EPiServer.Cms.WelcomeIntegration packages need to be updated to version 1.4.0
EPiServer.Cms.WelcomeIntegration.Graph needs to be installed

GraphClient needs to be configured in appsettings.json in the following way:

"Optimizely": {
  "ContentGraph": {
    "GatewayAddress": "https://cg.optimizely.com",
    "SingleKey": "SINGLE_KEY_FROM_CMP",
    "QueryPath": "content/v2",
    "UseHmacKey": false
  }
}

Make sure there is services.AddDAMUi(o => o.Enabled = true) call in Startup.cs
Add services.AddDAMGraphIntegration(); call to Startup.cs

If customer already has a CMS to Graph integration then it means he already has this config in appsettings

"Optimizely": {
  "ContentGraph": {
    "GatewayAddress": "https://cg.optimizely.com",
    "AppKey": "APPKEY",
    "Secret": "SECRET",
    "QueryPath": "content/v2"
  }
}

Those AppKey&Secret allow to read&write to a CMS schema. But our new CMP+Graph integration uses different schema which is now available with the CMS keys.

The following config needs to be added to appsettings.json

"EPiServer": {
  "Cms": {
    "CMPGraph": {
       "SingleKey": "SINGLE_KEY_FROM_CMP"
    }
  }
}

Or to Startup.cs

services.Configure<CMPGraphOptions>(options =>
{
    options.SingleKey = "YOUR_KEY_FROM_CMP";
});

In case the new package is not installed then it would still work as before, meaning all metadata will be fetched from the CMP API.

How to hide Reports from the global menu in Optimizely CMS

Thu, 08 Aug 2024 19:47:00 GMT

Reports section is available by default to all users who are members of the WebEditors group as the authorization policy of that MenuItem is set to

AuthorizationPolicy = CmsPolicyNames.CmsEdit,

So basically Reports section comes always together with the Edit Mode. However, I can imagine that sometimes reports are only useful to only a few specific editors and can be hidden from all others.

Unfortunately it is not possible to configure this anywhere but thanks to Optimizely's great and powerful extensibility it is possible to accomplish that requirement with just a few lines of code:

public class CustomMenuAssembler : MenuAssembler
{
	private readonly IPrincipalAccessor _principalAccessor;

	public CustomMenuAssembler(IEnumerable<IMenuProvider> menuProviders, IHttpContextAccessor httpContextAccessor,
		IPrincipalAccessor principalAccessor) : base(menuProviders, httpContextAccessor)
	{
		_principalAccessor = principalAccessor;
	}

	public override IEnumerable<MenuItem> GetMenuItems(string parentPath, int relativeDepth)
	{
		var menuItems = base.GetMenuItems(parentPath, relativeDepth).ToList();

		if (_principalAccessor.Principal.IsInRole("HasAccessToReportsGroup") == false)
		{
			return menuItems;
		}

		var reportItem =
			menuItems.SingleOrDefault(x => x.Path.Equals("/global/cms/report", StringComparison.Ordinal));

		if (reportItem == null)
		{
			return menuItems;
		}

		// Add user group check here
		menuItems.Remove(reportItem);

		return menuItems;
	}
}

So we create a new MenuAssembler which inherits from the default one and we pass the additional IPrincipalAccessor reference to it.

In my example I created a custom user group called HasAccessToReportsGroup . If an editor does not belong to this group then he/she will not see the Reports menu item.

Last we need to register this custom menu assembler and we need to make sure we do it after the built-in cms initialization modules are finished. Let's add a custom initializable module:

[InitializableModule]
[ModuleDependency(typeof(InitializableModule))]
public class DependencyResolverInitialization : IConfigurableModule
{
	public void ConfigureContainer(ServiceConfigurationContext context)
	{
		context.ConfigurationComplete += (_, _) =>
		{
			context.Services.AddSingleton<MenuAssembler, CustomMenuAssembler>();
		};
	}

	public void Initialize(InitializationEngine context)
	{

	}

	public void Uninitialize(InitializationEngine context)
	{

	}
}

The same approach can be used to conditionally hide all other menu items, you just need to change the path.

Please find the list of other paths:

/global/cms/report
/global/cms/dashboard
/global/cms/visitorgroups

How to prevent publishing a page with unpublished blocks or assets

Fri, 02 Feb 2024 16:37:19 GMT

EPiServer has a very powerful validation engine which is easily pluggable with custom validation rules.

I've been asked by a colleague to write a validation rule which would prevent a page from being published if it referenced an unpublished dependency (block/asset/...).

I thought it might be useful for some of you.

We need to hook to IContentEvents.PublishingEvent. We can do that from an initializable module:

[InitializableModule]
[ModuleDependency(typeof(EPiServer.Web.InitializationModule))]
public class PublishEventInitializationModule : IInitializableModule
{
    private DependenciesResolver dependenciesResolver;

    public void Initialize(InitializationEngine context)
    {
        //Add initialization logic, this method is called once after CMS has been initialized
        var contentEvents = ServiceLocator.Current.GetInstance<IContentEvents>();
        contentEvents.PublishingContent += contentEvents_PublishingContent;

        dependenciesResolver = ServiceLocator.Current.GetInstance<DependenciesResolver>();
    }

    void contentEvents_PublishingContent(object sender, EPiServer.ContentEventArgs e)
    {
        var dependencies = dependenciesResolver.GetUnpublishedDependencies(e.ContentLink).ToList();
        if (!dependencies.Any()) return;

        var text = dependencies.Count == 1 ? "dependency" : "dependencies";
        e.CancelAction = true;
        e.CancelReason =
            $"You can't publish because you have {dependencies.Count} unpublished {text}. {string.Join(',', dependencies.Select(x => $"{x.Name} [{x.ContentLink}] "))}";
    }

    public void Preload(string[] parameters)
    {
    }

    public void Uninitialize(InitializationEngine context)
    {
        //Add uninitialization logic
        var contentEvents = ServiceLocator.Current.GetInstance<IContentEvents>();
        contentEvents.PublishingContent -= contentEvents_PublishingContent;
    }
}

As you can see we calculate unpublished dependencies and cancel the operation if necessary.

DependencyResolver traverses the dependencies, both direct and nested, so validation will still fail if for example a page depends on an ImageBlock which has an unpublished ImageData.

Full gist is here: https://gist.github.com/barteksekula/78ff1df20df2f2449497d94c218cfdad

You can just copy paste the file to your project and it will work like this:

Opt-out from Inline Blocks support in ContentArea properties

Mon, 24 Jul 2023 14:58:25 GMT

WARNING: This post is no longer up to date because from CMS UI 12.23.3 inline blocks are no longer enabled by default.

They have to be turned on manually, more details here: https://world.optimizely.com/blogs/bartosz-sekula/dates/2023/5/inline-blocks-in-contentarea/
Or in the documentation https://docs.developers.optimizely.com/content-management-system/docs/inline-edit-settings

OLD BLOG POST BELOW:

In CMS 12.21.0 we added a way to create inline blocks inside each ContentArea property.

This feature is very powerful and has many advantaged as described in my previous blog post: https://world.optimizely.com/blogs/bartosz-sekula/dates/2023/5/inline-blocks-in-contentarea/

However, this also introduced issues for some clients, mostly non-MVC clients who rely on our API endpoints and always expected that each ContentAreaItem to have a non-null ContentLink.

For such cases in CMS UI 12.22.2 we added a way to opt-out from the ability to create inline blocks inside ContentArea.

This new setting is global and the default value is true

InlineBlocksInContentAreaEnabled is a new boolean property added to UIOptions class. You can set it directly in code or you can also use the appsettings approach as shown below:

"EPiServer": {
    "CmsUI": {
        "UI": {
            "InlineBlocksInContentAreaEnabled": false
        }
    }
}

After turning that flag to false the link to create an inline block in each ContentArea property will no longer be available.

Of course it is still possible to use the Assets pane to create shared blocks within the folder structure or use the `For this page/block` folder as contextual storage.

Important note: It is no longer possible to create shared blocks from Content Area.

12.22.2 also introduces a way to configure the labels for inline blocks.

By default inline blocks labels are just their type names. It is fine if there are just a few but if the list of blocks is long it may be very problematic to find the block you need to edit (because in contrast to the On-Page-Edit here you don't see the view of the block). We added a way to instruct ContentArea to use a specific property from block type as a label.

In order to do it you can use the new InlineBlockNamePropertiesOptions which can be set via appsettings.json in the following way:

"EPiServer": {
    "CmsUI": {
        "InlineBlockNameProperties": {
            "Contact": "Heading",
            "Teaser": "Heading"
        }
    }
}

It is a simple Dictionary<string, string> of BlockTypeName / PropertyName

Of course both options classes can be set in c#:

services.Configure<UIOptions>(o => {
    o.InlineBlocksInContentAreaEnabled = false;
});

services.Configure<InlineBlockNamePropertiesOptions>(options =>
{
    options.Add("Teaser", "Heading");
});

More details available here: https://docs.developers.optimizely.com/content-management-system/docs/inline-edit-settings

Inline blocks in ContentArea

Tue, 20 Jun 2023 12:05:59 GMT

WARNING: This post has been updated after releasing version CMS UI 12.24.0

Inline blocks are not enabled by default. Please scroll down to "How to enable this feature"

Introduction

EPiServer's most powerful property type ContentArea supports a number of use cases. Editors can store all kinds of content types there: pages, blocks, media, video, etc.

ContentArea does not just store references to those content items but additionally it stores their names, types and personalization information.

During the rendering phase property renderer loops through ContentAreaItems, applies personalization rules based on current identity and then tries to find a view for each item.

It is indeed quite flexible because it lets the editors to create any kinds of layouts using just a single property on a page or combining multiple ContentArea properties.

Editor can either select an existing IContent instance or decide to Create a new Block.

Blocks created via ContentArea were placed in `For this page/block` folders and were accessible through the Assets pane:

Because of the fact that each block is a separate IContent it is not possible to easily preview the changes, review by reviewers and finally to publish all items as once.

There were several attempts to solving this issue, one of them being the Block Enhancements Labs package:

https://nuget.optimizely.com/package/?id=EPiServer.Labs.BlockEnhancements

https://world.optimizely.com/blogs/grzegorz-wiechec/dates/2019/7/episerver-labs---block-enhancements/

https://world.optimizely.com/blogs/bartosz-sekula/dates/2021/9/block-enhancements-update/

It is a bit cumbersome that after creating a page with several blocks inside editor has to remember to always go through each page dependency to make sure it is in correct state. That each dependent block also has to be sent for review or added a project item even though it is only used once on that single page.

Inline blocks inside ContentArea

In EPiServer.CMS 12.22.3 we are releasing a big improvement to ContentArea. It is now possible to store BlockData inside ContentAreaItem as plain object.

There are no more tricks required to synchronize a parent page with dependencies to publish them all at once. Editor just need to deal with a single piece of content (page, multi-channel content, ..) and is now allowed to inline blockdata and make them part of that parent content.

Nothing changes in regards to property definition in code, ContentArea is still defined the same way:

public virtual ContentArea ContentItems { get; set; }

It is still possible to limit available content types by using AllowedTypes attribute

[AllowedTypes(typeof(TeaserBlock), typeof(EditorialBlock), typeof(ContactBlock)]
public virtual ContentArea ContentItems { get; set; }

The UI also stays the same:

However, after clicking Create new block we are no longer going to create a new instance of block which would be visible in For this page folder.

Instead we would create a property bag and inline that property bag into ContentAreaItem instance and store it inside the parent content.

After choosing the type and filling in the details:

We can immediately see the result:

After changing that ContentAreaItem we no longer need to publish the block but instead will get a new version of the parent page.

That has several implications:

Editor no longer needs to switch context to edit those inline blocks.
Inline blocks inside ContentArea do not have publishing lifecycle on their own, they are part of the page.
Those items also do not have approval workflow on their own. It is the parent content that has to be reviewed and approved.
Those items will not be included in projects, only their parent content as a whole

Let's say we publish the page now but after a while editor decides to change the test on our ButtonBlock

In order to do that we can just run the Edit command or double click the content area item.

Change the properties:

And after saving the dialog we can immediately see the changes on the page:

As you can see a new page version was created. We can easily preview how the page will look like after the changes. We can also use the compare mode:

All properties mode

Inline blocks can be named as any other blocks however for some simple block types it may be that there is already a textual property which can be used instead (for example if you have a Heading property in your ContactBlock or TeaserBlock.

In order to do it you can use the new InlineBlockNamePropertiesOptions which can be set via appsettings.json in the following way:

"InlineBlockNameProperties": {
    "Contact": "Heading",
    "Teaser": "Heading"
}

It is a simple Dictionary<string, string> of BlockTypeName / PropertyName

After that for ContactBlock and TeaserBlock instances Name will no longer be displayed in Create new block dialog and also the value of Heading property will be used in Content Area editor.

View Mode Rendering

No special attributes or techniques are needed in order to render inline blocks. If you use our HtmlHelpers or TagHelpers they will render exactly the same as regular blocks.

If you have a display template defined for a specific block type then the runtime will pick it up and use.

Migration

If you have existing local or shared blocks which you would like to inline into ContentArea properties then you have two options:

We added a utility command which converts ContentAreaItem to an inline version. The original IContent is not removed, you will need to clean up manually
There is an admin mode plugin available in Block Enhancements Labs 1.2.2

The migration can be done in 3 steps:

Convert shared blocks used only once to their respective `For this page` folder
Make blocks from `For this page` inlined into ContentArea properties
Remove empty folders from assets pane.

All the steps can be either run at once or separately. It's up to you.

It is also possible to run the migration the other way around. If you have inline blocks in the system and would like to turn them off and switch back to shared blocks then please use `Convert inline to shared` link or scheduled job. You can use `Dry run` to list all conten items containing inline blocks.

Changes to ContentArea `Create a new block` command

Prior to CMS 12.22.3 clicking on `Create a new block` link button:

Would create the new block inside `For this page` folder. After upgrading to CMS 12.22.3 it creates an inline blocks and embeds it inside ContentArea property.

Changes to shared content

Each shared item (essentially every content instance which has an ID and can be referenced by something else) will be clearly marked with `SHARED` label. Both in Forms view and in On-Page Edit.

Additionally when editing a shared block through `Quick Edit` we now display a warning if that item being edited is used more than once:

ContentAreaItem property

Another enhancement is that we added the possibility to define a single ContentAreaItem property. It looks as a regular ContentReference property but offers much more functionality.

Essentially it works as a ContentArea with a single item limitation applied.

public virtual ContentAreaItem MyContentItem { get; set; }

It is also possible to limit available content types by using AllowedTypes attribute

[AllowedTypes(typeof(TeaserBlock), typeof(EditorialBlock), typeof(ContactBlock)]
public virtual ContentAreaItem MyContentItem { get; set; }

The UI resembles a regular ContentReference:

However apart from storing just a reference it also allowes you to create and store an inline block inside:

This property will also work fine in OPE and will support display options, the same way as in ContentArea (we reuse ContentAreaRenderer).

Q&A

Q: What happens after upgrading to CMS 12.22.3? Is there any automatic content migration?

A: No. This is not a breaking release. Nothing will happen to your content. However, please be aware that inline blocks DO NOT HAVE content links on their own. They are just simple property bags.

Q: How to start using this new feature?

A: Please scroll down to `How to enable this feature`

Q: Is this also supported through the API

A: Yes. All the things you can do from Edit Mode are supported through our Management API

Q: Does ContentArea still support old functionality?

A: Yes, ContentArea still supports storing ContentReference, it still supports personalization, display options etc.

EPiServer.Labs.BlockEnhancements

That package is going away. All of its functionalities are now part of the main package. The last remaining feature is the migration tool described above.

There will be no further releases.

How to enable this feature

You can either use UIOptions.

services.Configure<UIOptions>(uiOptions =>
{
    uiOptions.InlineBlocksInContentAreaEnabled = true;
});

or via appsettings.json

"EPiServer": {
    "CmsUI": {
        "UI": {
            "InlineBlocksInContentAreaEnabled": true
        }
    }
}

Documentation for this feature can be found here https://docs.developers.optimizely.com/content-management-system/docs/inline-edit-settings

Official List property support

Tue, 28 Mar 2023 12:16:26 GMT

Introduction

Until now users were able to store list properties in three ways:

Store simple types (int, string, DateTime, double) as native properties like IList<string>, IList<int>, etc.. as described in https://world.optimizely.com/blogs/bartosz-sekula/dates/2017/10/property-value-list/
Use a custom EPiServer.Core.PropertyList<T> which was introduced in CMS9 and described in a nice way in this blog post https://world.optimizely.com/blogs/Per-Magne-Skuseth/Dates/2015/11/trying-out-propertylistt/
Use block reference list of any kind like a Content Area, or a list of ContentReference

All those approaches had its own issues and limitations.

The first one's obvious limitation was that it was only able to operate on very basic types. On the other hand it provided a nice editing experience with an inline value editor and autosave.

The next one was much more powerful because it allowed the user to use any kind of POCO and then render the list in a tabular way:

and let the user edit each item from within a dialog:

However this approach also had a few issues:

Property values are serialized to JSON and stored as plain string in the database
Permanent links are not validated
Some things like import/export, default values, custom metadata extenders need to be implemented manually

Finally the approach with using ContentArea or a list of ContentReference in theory solves all those issues because the editor has the ability to define the block list item anyhow and is able to use existing properties, however each list item is a separate IContent instance which has its own publishing lifecycle. In addition it also goes through the same approval process, can be included in a project as project item etc.

Because of the fact that each block is a separate IContent it is not possible to easily preview the changes or publish all items as once.

There were several attempts to solving this issue, one of them being the Block Enhancements Labs package:

https://nuget.optimizely.com/package/?id=EPiServer.Labs.BlockEnhancements

https://world.optimizely.com/blogs/grzegorz-wiechec/dates/2019/7/episerver-labs---block-enhancements/

The new list property

In EPiServer.CMS 12.18.0 we are releasing a brand new list property which solves all the issues outlined above.

Adding a list property is as simple as:

public virtual IList<ContactBlock> Contacts { get; set; }

Where ContactBlock can be defined like this:

[ContentType(AvailableInEditMode = false, GUID = "38d57768-e09e-4da9-90df-54c73c61b270")]  
public class ContactBlock : BlockData  
{  
   //block properties  
}

What is important here is the fact that each ContactBlock instance will not be a content item of its own but will be stored inside its parent.

That fact has several implications:

Editor no longer needs to switch context to edit those inline blocks
Inline blocks do not have publishing lifecycle meaning that whenever any list item is changed the user the editor will see a new version of the current content being created
List items will inherit approval sequence from their parent, it is the parent content that has to be reviewed and approved
List items will not be included in projects, only their parent content as a whole

The editor of such contact block list will look like this:

Of course, having the ability to make the blocks inline is the primary use case of the new List<T> however it is capable of storing any kind of property type inside.

Users can still utilize basic types like:

public virtual IList<int> Numbers { get; set; }

public virtual IList<string> Strings { get; set; }

public virtual IList<DateTime> Dates { get; set; }

But it is also possible to use more complex types:

public virtual IList<XHtmlString> XHtmlStrings { get; set; }

Or for example create a list of images or videos:

[ListItemUIHint(UIHint.Image)]
public virtual IEnumerable<ContentReference> Images { get; set; }

Which will be rendered like this:

Please note that the property is annotated with a new attribute ListItemUIHintAttribute which works the same as regular UIHint but applies to the generic type of the list item.

So we are telling the List property to use UIHint.Image for individual items.

It is still possible to use UIHint("YourCustomListEditor") if you have your own editor.

Rendering

No special attributes or techniques are needed in order to render a list of any property types.

The only thing needed is to provide a display template for a single item and the CMS will do the rest by wrapping each item in a list item.

public virtual IList<EditorialBlock> Blocks { get; set; }

You will just need to provide EditorialBlock.cshtml which could look like this:

@model EditorialBlock

<div class="clearfix" @Html.EditAttributes(x => x.MainBody)>
    @Html.DisplayFor(x => Model.MainBody)
</div>

And to render the `Blocks` property on the page you can use either HtmlHelpers package:

@model MyPage

@Html.PropertyFor(x => x.EditorialBlocks)

Or the new TagHelpers package:

@model MyPage

<div epi-property="EditorialBlocks" />

Migration

The data model behind the scenes is much different from the previous implementations which always were based on some sort of JSON serialization.

There is no automatic way to migrate from the old model to the new one and all migrations might different from case to case but let's imagine a hypothetical scenario like this:

Let's say we have a page MyPage.cs with a single property inside:

public class MyPage : PageData 
{
   [EditorDescriptor(EditorDescriptorType = typeof(CollectionEditorDescriptor<Person>))]
   public virtual IList<Person> PersonList { get; set; }
}

public class Person
{    
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int Age { get; set; }
    public string Email { get; set; }
}

[PropertyDefinitionTypePlugIn]
public class PersonListProperty : PropertyList<Person>
{
    public PersonListProperty()
    {
        _objectSerializer = _objectSerializerFactory.Service.GetSerializer(KnownContentTypes.Json);
    }

    private Injected<IObjectSerializerFactory> _objectSerializerFactory;

    private IObjectSerializer _objectSerializer;

    protected override Person ParseItem(string value)
    {
        return _objectSerializer.Deserialize<Person>(value);
    }
}

The property would look like this in Edit Mode:

In order to migrate to the new property and use the new inline editor we would have to:

Define a new PersonBlock type and mark it as AvailableInEdit = false

[ContentType(AvailableInEditMode = false, GUID = "11157768-e09e-4da9-90df-54c73c61b270")] 
public class PersonBlock : BlockData
{    
    public virtual string FirstName { get; set; }
    public virtual string LastName { get; set; }
    public virtual int Age { get; set; }
    public virtual string Email { get; set; }
}

In order to use it on MyPage:

public class MyPage : PageData 
{
   public virtual IList<PersonBlock> PersonsNew { get; set; }
}

And the new editing experience will look like this:

Please note that it is no longer necessary to define your own property type.

In order to migrate from IList<Person> to IList<PersonBlock> a custom piece of code which iterates over all instances of MyPage analyzes what is inside PersonList property and then uses the same values to create an a list of PersonBlock instances.

Next improvements coming up

We are planning to take it even further and allow to inline blocks into Content Area as well so stay tuned for next updates on that matter.

Eventually we will turn off `Quick edit` command and promote the new Inline Blocks which no longer need any kind of tricks to keep their publishing lifecycle synchonized with their parent.

We will also not need any commands like `Publish page with blocks` https://github.com/episerver/EPiServer.Labs.BlockEnhancements#publish-page-and-shared-blocks

Obsoleting EPiServer.Labs.BlockEnhancements

The whole idea of `inlining` the blocks into page came up as part of our Labs initiative which turned out to be highly successful https://github.com/episerver/EPiServer.Labs.BlockEnhancements#local-content

Now, since most of Labs functionality ends up in the official package it is time to deprecate it.

Built-in support for single LinkItem property

Wed, 14 Sep 2022 12:35:49 GMT

EPiServer.CMS 12.11.0 introduces a new property type LinkItem . This feature has been one of the most requested features for a long time.

The feature is very simple: it is to allow the editor to choose a single LinkItem.

After clicking the `Add Link` button editor is presented with the standard Linkitem dialog:

After selecting any content item the editor will look like this:

In order to use the new property type you just need to use the LinkItem data type. No annotations are needed.

public class PartnerPage : PageData
{
    public virtual LinkItem MyLink { get; set; }
}

Migration from EPiServer.Labs.LinkItemProperty

If you used the Labs package before and you wish to update then you will need to follow a few manual upgrade steps:

Labs used the following:

public class PartnerPage : PageData
{
    [LinkItemProperty]
    [BackingType(typeof(PropertyLinkCollection))]
    public virtual LinkItem Link
    {
        get => this.GetLinkItemPropertyValue(nameof(Link));
        set => this.SetLinkItemPropertyValue(nameof(Link), value);
    }
}

You have to remove both LinkItemProperty and BackingType annotations and switch to auto property.

public class PartnerPage : PageData
{
    public virtual LinkItem Link { get; set; }
}

You will also need to run the following SQL command (don't forget to do the backup for safety)

DECLARE @PropertiesToUpdate NVARCHAR(4000); -- one or more coma separated properties to update with [ContentTypeName.PropertyName] format
SET @PropertiesToUpdate = ''; -- for example ArticlePage2.SingleLink,ArticlePage2.SingleLinkCultureSpecific

-- update published versions
UPDATE tblContentProperty
 SET tblContentProperty.LongString = SUBSTRING(  -- start after `<links>`
           SUBSTRING(propValue.LongString, 0, CHARINDEX('</a>',  propValue.LongString) + 4), -- remove all text after first `</a>`
           8, 100000)
 OUTPUT INSERTED.*, deleted.*
  FROM tblPropertyDefinition propDef
  JOIN tblPropertyDefinitionType propDefType ON propDefType.[Name] = 'LinkCollection'
   AND propDef.fkPropertyDefinitionTypeID = propDefType.pkID
  JOIN tblContentType ON tblContentType.pkID = propDef.fkContentTypeID
  JOIN tblContentProperty propValue ON propValue.fkPropertyDefinitionID = propDef.pkID
 WHERE propValue.LongString LIKE '<links>%'
   AND CHARINDEX(tblContentType.[Name] + '.' + propDef.[Name] + ',', @PropertiesToUpdate + ',') > 0;

-- update versions  
UPDATE tblWorkContentProperty
   SET tblWorkContentProperty.LongString = SUBSTRING(  -- start after `<links>`
          SUBSTRING(propValue.LongString, 0, CHARINDEX('</a>',  propValue.LongString) + 4), -- remove all text after first `</a>`
          8, 100000)
OUTPUT INSERTED.*, deleted.*
  FROM tblPropertyDefinition propDef
  JOIN tblPropertyDefinitionType propDefType ON propDefType.[Name] = 'LinkCollection'
   AND propDef.fkPropertyDefinitionTypeID = propDefType.pkID
  JOIN tblContentType ON tblContentType.pkID = propDef.fkContentTypeID
  JOIN tblWorkContentProperty propValue ON propValue.fkPropertyDefinitionID = propDef.pkID
 WHERE propValue.LongString LIKE '<links>%'
   AND CHARINDEX(tblContentType.[Name] + '.' + propDef.[Name] + ',', @PropertiesToUpdate + ',') > 0;

-- update property type
UPDATE tblPropertyDefinition
   SET tblPropertyDefinition.fkPropertyDefinitionTypeID = (SELECT pkID from tblPropertyDefinitionType where [Name] = 'LinkItem')
OUTPUT INSERTED.*, deleted.*
  FROM tblContentType
 WHERE tblPropertyDefinition.fkPropertyDefinitionTypeID = (SELECT pkID from tblPropertyDefinitionType where [Name] = 'LinkCollection') 
   AND CHARINDEX(tblContentType.[Name] + '.' + tblPropertyDefinition.[Name] + ',', @PropertiesToUpdate + ',') > 0;

Afterwards the Labs package can just be uninstalled.

Block Enhancements Update

Wed, 27 Oct 2021 08:38:07 GMT

We have just released a new version of EPiServer.Labs.BlockEnhancements 0.11.0 and we would really love to hear your feedback. Please find what it brings to the Editors!

It greatly enhances the way editors have to deal with local content - which means content that is not shared accross multiple other pages but used only once.

Such local content is typically stored in `For this page/block` folders and is considered an integral part of the page. It turns out that on average more than 90% of blocks are only used on a single page which means that they either already reside in `For this page` folder or could easily be moved there.

After installing/upgrading to 0.11.0 editors no longer have to manage Local Blocks and Local Assets independently. All local contents (meaning content that resides in For this page/block folders) lifecycle will now be synchronized to its parent.

This greatly simplifies the process of creating and editing pages because editor/reviewer no longer need to deal with individual blocks or assets but can focus on the big picture.

When publishing a page all local content will be published altogether.

The same with approval workflow, when content is marked as Ready to review, Approved or Declined then the editor/reviewer will just receive a single notification about the page. There will be no need to review the block individually.

Changing a local block will create a new page version which lets the editors to review and preview what actually changed on a given page.

Please see the new feature in action:

This allows the editor to use the Compare Mode and see what actually changed:

Editor can also mark the page as Ready to review without dealing with local blocks one by one

Approving/declining is just as easy:

We also added an admin mode plugin that lets you analyze the blocks on your site:

All the blocks that are not truly Shared (meaning they are only used once) will be moved the the respective `For this page/block` folders. You can move the blocks one by one or move all the visible blocks at once.

For performance reasons we only display the N first blocks that match the search filter.

In this version we removed two features:

Content Draft View - it is no longer needed because version 0.11.0 makes the preview work automatically for all local content. The editor no longer needs to know that some parts of the page are not published, everything that builds a page is one entity that is saved, previewed and published at the same time. However, all shared content items (pages, shared blocks, shared media) have to be managed on their own.
Inline Publish from Content Area - it was not popular and is no longer needed since now you can just publish the page and all local dependencies do not have to be handled separately and will be published automatically. Shared content has to be published on its own.

Additionally we disabled the `Publish Page with Blocks` aka `Smart publish` by default - the command can still be turned on via Options if you really need to because you already have many shared blocks that cannot be convert to local blocks. We would like this command to be phased out eventually. Blocks which are truly shared between multiple pages should be published from their respective context where the editor can clearly see the list of items that will be affected by the change.

Idea of linking pages with their local content seems more attractive.

Documentation and full source code is available on our github https://github.com/episerver/EPiServer.Labs.BlockEnhancements and this specific feature is available here https://github.com/episerver/EPiServer.Labs.BlockEnhancements#local-content

If you find any issue or would like to contribute then you are more than welcome to let us know :)

We are also in the middle of migrating this Labs package to .net core. It will be available soon!

How to resolve current content context

Tue, 28 Sep 2021 08:38:11 GMT

With the release of CMS UI 11.36.2 it is now possible to resolve the current loaded content context from anywhere you may need.

It might be useful if you need any custom logic in any of the Content Events:

[ModuleDependency(typeof(EPiServer.Shell.UI.InitializationModule))]
public class CustomModule : IConfigurableModule
{
    public void Initialize(InitializationEngine context)
    {
        context.Locate.ContentEvents().CreatedContent += CreatedContent;
        context.Locate.ContentEvents().CreatingContent += CreatingContent;
    }

    private void CreatingContent(object sender, ContentEventArgs e)
    {   
        var currentContentContext = ServiceLocator.Current.GetInstance<CurrentContentContext>();
        // we know which content context initiated the CREATE operation        
        var currentContentLink = currentContentContext.ContentLink;

        var newlyCreatedContentLink = e.ContentLink; // --> null as at this point the ContentReference was not assigned yet
    }

    private void CreatedContent(object sender, ContentEventArgs e)
    {
        var newlyCreatedContentLink = e.ContentLink; // this is the ContentReference of the newly created content item
        // but we might need the ContentReference of the content that was being viewed when the CREATE operation was run
        var currentContentContext = ServiceLocator.Current.GetInstance<CurrentContentContext>();
        // this gives us the content context the editor was in
        var currentContentLink = currentContentContext.ContentLink;
    }

    public void Uninitialize(InitializationEngine context)
    {
        context.Locate.ContentEvents().CreatedContent -= CreatedContent;
        context.Locate.ContentEvents().CreatingContent -= CreatingContent;
    }

    public void ConfigureContainer(ServiceConfigurationContext context)
    {

    }
}

You might also need to know the current context in metadata aware components, like for example in this Editor Descriptor:

public class FooPageType : PageData 
{
    [EditorDescriptor(EditorDescriptorType = typeof(CollectionEditorDescriptor<OfferDetailsItem>))]
    public virtual IList<OfferDetailsItem> OfferDetailsItems { get; set; }
}

public class OfferDetailsItem
{
    [Display(Order = 1)]
    [UIHint("test")]
    public string Label { get; set; }
}

[PropertyDefinitionTypePlugIn]
public class OfferDetailsItemPropertyList : PropertyList<OfferDetailsItem>
{
}

[EditorDescriptorRegistration(TargetType = typeof(string), UIHint = "test")]
public class CustomXhtmlDescriptor : StringEditorDescriptor
{
    private readonly CurrentContentContext _currentContent;

    public CustomXhtmlDescriptor(CurrentContentContext currentContent)
    {
        _currentContent = currentContent;
    }

    public override void ModifyMetadata(ExtendedMetadata metadata, IEnumerable<Attribute> attributes)
    {
        base.ModifyMetadata(metadata, attributes);

        var ownerContent = metadata.FindOwnerContent(); // --> will return null because the object we annotate is not ContentData but simple POCO
        // https://world.optimizely.com/forum/developer-forum/CMS/Thread-Container/2016/1/current-content-for-propertylist-item-selection-factory/
        // and
        // https://world.optimizely.com/forum/developer-forum/CMS/Thread-Container/2021/9/tinymce-customization-depending-on-page-context/
        var currentContent = _currentContent.ContentLink; // --> will return correct page id
    }
}

Related forum posts that describe the problem:

https://world.optimizely.com/forum/developer-forum/CMS/Thread-Container/2021/9/tinymce-customization-depending-on-page-context/

https://world.optimizely.com/forum/developer-forum/CMS/Thread-Container/2020/12/get-value-of-contextepi-cms-contentdata/#234848

https://world.optimizely.com/forum/developer-forum/CMS/Thread-Container/2016/1/current-content-for-propertylist-item-selection-factory/

Refresh current editing context on property value change

Tue, 07 Sep 2021 12:16:25 GMT

With the release of CMS UI 11.36.0 it is now possible to annotate any model property with a new attribute from EPiServer.Cms.Shell.UI.ObjectEditing namespace called ReloadOnChangeAttribute.

Imagine a simplified scenario - we have a list of available options

[Display(GroupName = Global.GroupNames.MetaData, Order = 250)]
[SelectOne(SelectionFactoryType = typeof(ItemsSelectionFactory))]
public virtual string Items { get; set; }

but the list should be filtered based on some extra property value also defined in our model:

[Display(
    GroupName = "EPiServerCMS_SettingsPanel",
    Order = 2)]
public virtual bool Important { get; set; }

Now, we would like a different set of items to be displayed when Important flag is on and different when Important flag is off.

All we have to do is to annotate our conditional property with the new attribute:

[Display(
    GroupName = "EPiServerCMS_SettingsPanel",
    Order = 2)]
[ReloadOnChange]
public virtual bool Important { get; set; }

And now we can utilize the value of Important property inside our factory.

public class ItemsSelectionFactory : ISelectionFactory
{
    public IEnumerable<ISelectItem> GetSelections(ExtendedMetadata metadata)
    {
        var content = metadata.FindOwnerContent();
        var property = content?.Property[nameof(SitePageData.Important)];
        if (property?.Value != null && (bool) property.Value)
        {
            return new[]
            {
                new SelectItem
                {
                    Text = "VERY IMPORTANT ITEM 1",
                    Value = "100"
                }
            };
        }

        return new[]
        {
            new SelectItem
            {
                Text = "NOT IMPORTANT ITEM 1",
                Value = "1"
            },
            new SelectItem
            {
                Text = "NOT IMPORTANT ITEM 2",
                Value = "2"
            },
            new SelectItem
            {
                Text = "NOT IMPORTANT ITEM 3",
                Value = "3"
            }
        };
    }
}

The same applies to OPE. Let's say you only need a specific box to be shown when the Important flag is on. All you need to do is to just read the value in the template and on every value change the template will be rerendered:

@if (Model.CurrentPage.Important)
{
    <div style="height: 100px; width: 100px; background-color: red;"></div>
}

This is how it looks in action:

Forms compatibility package with Labs.BlockEnhancements

Thu, 23 Apr 2020 17:04:47 GMT

Block Enhancements Labs package does not fully support EPiServer Forms so if you use both packages in one of your sites then you may need a tiny compatibility package that I have just released a new version v0.2.0 of.

The source code is Open Source, more details can be found here: https://github.com/advanced-cms/forms

The nuget can be installed from https://nuget.episerver.com/package/?id=Advanced.CMS.Forms&v=0.2.0

The package lets you configure the Forms without changing the Editing Context which is a bit more convenient when working with compex and long forms:

It also works in OPE:

It is not an official package from EPiServer but is actively maintained by the "advanced-cms" team (Greg & Bart).

Content Manager - lightweight editing UI

Mon, 20 Apr 2020 06:48:23 GMT

It's a pleasure to announce the release of two new Episerver Labs packages (more info about Labs in general can be found here).

Content Manager - which is a new feature that allows you to manage content items outside of Edit Mode.
Grid View - which is an add-on that helps you to manage large volumes of data inside Edit Mode.

In the following weeks, we will be discussing both packages in details in separate blog posts not to overwhelm you with too much information.

NuGet packages are available here:

https://nuget.episerver.com/package/?id=EPiServer.Labs.ContentManager

https://nuget.episerver.com/package/?id=EPiServer.Labs.GridView

IMPORTANT!

As of now Content Manager package is still dependent on the GridView package, so if you plan to give Content Manager a try then you must install both packages.

Documentation is available here:

https://github.com/episerver/episerver-labs-content-manager-docs

Please report bugs/issues/questions here: https://github.com/episerver/episerver-labs-content-manager-docs/issues

Let's just take a quick look on what is possible with the new packages!

There are two ways we can organize content:Introduction

The first one is Structured. You are all familiar with it as it's widely used in CMS to display the sites as Tree Views or to display Asset folder structures.

This model has been there for a long time and is very well supported by current Episerver product family.

However, more and more frequently there are requirements to have parts of the system that does not fit into such tree model.

We saw a lot of solutions where only a small part of the system was hierarchical while the major part of content items was placed in a single container.

The web is changing, and content no longer means what it used to mean 10 years ago.

Now, a content item is not necessarily only a web page, it may not have an addressable URL and it may be just a container for data that can be seen as a database record.

Sometimes, the same piece of content can be used on a page, on social media or in print which means the content is no longer assigned to a specific channel. Usually, those kind of content items are simple with only basic property types and some metadata.

When trying to use large volumes of structureless content in the current Edit Mode, we easily might get into trouble. The tree is not optimized to display long lists of children items under a single node. It is easy to solve this with some kind of clustering but everything comes with a price. Clustered content is much harder to find and to work with.

Another option is to use the Episerver Search & Navigation package (formerly Episerver Find) together with the PowerSlice add-on which allows you to get page lists by page type but its functionality is limited and not customizable.

Hopefully, with the release Grid View, it will be much easier for the editors.

Grid View

Grid View, started some time ago by Greg ( https://gregwiechec.com/2017/11/content-childrengrid-view/) gives you a way to mark such a node as a 'Container' and browse its descendants in a dedicated custom view which gives a much better navigation and filtering.

It is possible to convert a page/folder to a 'container' either by code or by the admin interface (it will all be explained in detail in future posts).

One more Grid View feature worth mentioning is the ability to turn off the Page Tree and use the Grid as an alternative:

It offers the same functionality, such as context menus and D&D, so it can be used interchangeably with the Tree.

Grid View gives much more functionality and is highly customizable (it will all be covered in future posts).

Content Manager

Edit Mode is very powerful. It contains a lot of features which makes it powerful but as with all feature-rich products that also causes that it takes time to learn how to use it properly.

Some editors may use it to its full extent; however, some editors may just need the very basic functionalities.

Content Manager is designed to be an alternative for Edit Mode, offering a subset of functionality in a modern and mobile-friendly UI.

It does not focus on web specifically; there is no page tree, no concept or URLs, SEO optimization, publishing workflows etc. It is just a way to edit content items that can later be used in any other channel like social media, web, print and so on.

It is available to use right after installing the NuGet package. By default, it will present the content items from the whole site.

Dashboard

As you can see it looks much different from what we are used to in Edit Mode. There is no tree or panes etc. Instead you get a powerful full-text search with configurable autocomplete, a few content queries and the ability to quickly create a new content item directly from the Dashboard.

The Dashboard View is completely configurable:

All areas marked in yellow can be adjusted by the developer or an admin.

List View

Content Manager allows to create multiple List View instances. Each can display different Content Types, and each can fetch items from a different folder or even an external content provider.

Adding and configuring List View instances will be covered in detail in the following blog posts and in our documentation.

The purpose of this screen is to give the ability to find and browse content items. You can either use the Card view:

Or a table view:

On the left, you can find two facets that let you filter by Changed Date and current Content Status.

Each item is editable:

The review workflow is greatly simplified. The user of Content Manager just marks the item as 'Ready'. It is not important whether there's a Content Approval workflow configured behind the scenes or the item is just marked as 'Ready to Publish'. This makes it much easier.

It is easy to create a setup where you have one "super editor" with access to Edit Mode. That user would configure the approval workflows, publish pages etc. but would also review content items created by "content editors" using the new Content Manager. All the 'publishing & review' complexity is entirely handled by the 'super editor' from Edit Mode.

Content Manager makes it much easier to perform the basic editing operations.

Managing Media Files

Content Manager can also be used to work with Digital Assets. It is possible to configure a List Instance to display image files. Then the 'Add new' button is replaced with an 'Upload image' option.

Mobile friendly

Content Manager works fine on mobile and tablets. It's fully responsive.

So for example, it is very easy to just open Content Manager on your phone, open the DAM View, click upload image and take a photo with your phone, which will automatically upload the image to a preconfigured folder.

Performance

The data is available through an abstraction. We wrote two implementations:

Default data repository - included in the main NuGet package and uses the native Episerver.Data api and works to a certain volume of data. (We might try to optimize the performance of the default implementation after v1.)
Data repository based on the Episerver Search & Navigation package - https://nuget.episerver.com/package/?id=EPiServer.Labs.ContentManager.Core.FindQuery If you already use Episerver Search & Navigation in your solution, then after installing that extra NuGet package, Content Manager will start fetching data from the index giving you a much better performance and scalability. The volume of data is no longer an issue.

External content providers

As mentioned before, it is very easy to use Content Manager to manage content stored outside of the Episerver database and accessible via a Custom Content Provider.

For example to expose the Product Catalog from your Commerce instance and let the product management team edit the catalog without the need to log in to Edit Mode.

Q&A

It is important to note that NO changes in the site configuration are required (no changes in models, business logic, etc.).

It is just enough to install the NuGet to get the default configuration which can be adjusted later on.

Every feature is opt-in by default.

Feedback

We would really appreciate any kind of feedback. Stay tuned for more information!

Translate content items without switching context

Thu, 16 Apr 2020 05:38:34 GMT

We have just released a new version of EPiServer.Labs.BlockEnhancements v0.8.0 that contains an improvement for multilingual sites.

Editors will now be able to create language versions without the need to first navigate to the item and lose their current Editing Context.

As you can see, the Inline Edit command is not available if the item does not exist in the current editing language.

After clicking 'Create {missingLanguage} language version' a dialog will pop out with a list of language specific properties. It will include both required and optional properties so that the content item can be created in one go.

Of course the new command is also available from the Assets Pane.

If you haven't tried the Block Enhancements labs yet go ahead and install from https://nuget.episerver.com/package/?id=EPiServer.Labs.BlockEnhancements&v=0.8.0

The add-on is open-source, source code is available on our github https://github.com/episerver/EPiServer.Labs.BlockEnhancements

We would, as always, appreciate your feedback!

Inline Block Publishing - create new blocks without leaving current context

Wed, 06 Nov 2019 09:47:13 GMT

We added a new major improvement to the block publishing that I would like to share with you.

Previously, the editors were able to only inline edit existing blocks. However, whenever a new block was needed then they still had to use the default form, that caused the current content context to switch.

It was quite annoying especially in nested block scenarios where you had several levels of nesting i.e. Bootstrap Row Blocks containing Content Blocks.

With https://nuget.episerver.com/package/?id=EPiServer.Labs.BlockEnhancements&v=0.5.0 it is now possible to create new blocks using the same inline form, without the need to ever leave the current context.

The best part is that we support nesting. As many levels as needed. And it works both in On-Page Edit (OPE) and in regular Forms view.

After upgrading to v0.5 the "Create a new block" link will no longer open a big content type selector and switch editor's context to the newly created content item.

Instead a simple dialog will be presented:

After choosing the content type the editor will see the inline edit form straight away. All properties will be included (both required and optional):

Please note that the new commands are available both from the Forms View and the On-Page Edit.

Please take a look how it all works:

Editing enhancements for the EPiServer.Forms package

Mon, 14 Oct 2019 11:06:00 GMT

Together with Greg we created a little, yet powerful add-on that brings enhancements from EPiServer.Labs.BlockEnhancements to EPiServer.Forms based properties.

Editor is now able to edit every form inline, without the need to switch the editing context. Just double click any Form Element to edit its properties. Then use Inline Publish to public the Form Element.

You can install it from here:

https://nuget.episerver.com/package/?id=Advanced.CMS.Forms

The source code is available here:

https://github.com/advanced-cms/forms

The addon is MIT licensed. Feel free to use/contribute however you want.

Nice improvement for the Inline Editing feature

Sun, 13 Oct 2019 20:51:00 GMT

I have just pushed a nice little improvement that lets the editor to double-click a block and edit its properties straight away.

No context switching, no context menus or finding the rights commands, just double click an item in the Content Area and you're good to go!

More info here:

https://github.com/episerver/EPiServer.Labs.BlockEnhancements#inline-block-editing

v0.4.0 is available here:

https://nuget.episerver.com/package/?id=EPiServer.Labs.BlockEnhancements&v=0.4.0

Blog posts by Bartosz Sekula

Side by side editing - stable release

Side by side editing - alternative to Optimizely On-Page Edit

How to add an Admin Mode add-on in Optimizely CMS12

Useful Optimizely CMS Web Components

CMS + CMP + Graph integration

How to hide Reports from the global menu in Optimizely CMS

How to prevent publishing a page with unpublished blocks or assets

Opt-out from Inline Blocks support in ContentArea properties

WARNING: This post is no longer up to date because from CMS UI 12.23.3 inline blocks are no longer enabled by default.

They have to be turned on manually, more details here: https://world.optimizely.com/blogs/bartosz-sekula/dates/2023/5/inline-blocks-in-contentarea/Or in the documentation https://docs.developers.optimizely.com/content-management-system/docs/inline-edit-settings

OLD BLOG POST BELOW:

Inline blocks in ContentArea

WARNING: This post has been updated after releasing version CMS UI 12.24.0

Inline blocks are not enabled by default. Please scroll down to "How to enable this feature"

Introduction

Inline blocks inside ContentArea

All properties mode

View Mode Rendering

Migration

Changes to ContentArea `Create a new block` command

Changes to shared content

ContentAreaItem property

Q&A

EPiServer.Labs.BlockEnhancements

How to enable this feature

Official List property support

Introduction

The new list property

Rendering

Migration

Next improvements coming up

Obsoleting EPiServer.Labs.BlockEnhancements

Built-in support for single LinkItem property

Migration from EPiServer.Labs.LinkItemProperty

Block Enhancements Update

How to resolve current content context

Refresh current editing context on property value change

Forms compatibility package with Labs.BlockEnhancements

Content Manager - lightweight editing UI

There are two ways we can organize content:Introduction

Grid View

Content Manager

Dashboard

List View

Managing Media Files

Mobile friendly

Performance

External content providers

Q&A

Feedback

Translate content items without switching context

Inline Block Publishing - create new blocks without leaving current context

Editing enhancements for the EPiServer.Forms package

Nice improvement for the Inline Editing feature

They have to be turned on manually, more details here: https://world.optimizely.com/blogs/bartosz-sekula/dates/2023/5/inline-blocks-in-contentarea/
Or in the documentation https://docs.developers.optimizely.com/content-management-system/docs/inline-edit-settings