Episerver: How To Render A List Of Objects In a Page Or Block… PropertyList Explained

When Episerver moved towards a Page/Block architecture, it provided a lot more flexibility of how content editors could use and manipulate. One feature that was available in Episerver 6 (using a custom extension) but was dropped, was the ability to display a list of C# classes as a property within the CMS that content editors could update.

Until Episerver 9, you could only implement this functionality by creating a custom Dojo widget, or, via blocks. As part of the Episerver 9 release, a new property is available to developers, the List property to enable this functionality.

Why Use List/

There are a couple of great reasons to use the List property over a block. First, performance… adding blocks within a content area required API calls to either get the objects from the database or, cache. Using a List means you can make a single API call to get the content without needing to make additional calls.

Second, improved usability for content editors. Having a list of items on the page, means content editor don’t have to jump into a block view to add and edit data. From my experiences using Episerver, the more content editor have to jump around, from content areas to a sub-block, the unhappier they seem to be. Making the content editor’s life as quick as possible will gain you some invaluable brownie points!

The Code

Ok, so we’ve covered some of the benefits of using List, let’s cover the code. In this example, I’m going to create a simple section a content editor could use to add a list of awards the company has won. First we need an object that defines the list items we want the content editors to be able to edit:

public class Award
{
public string AwardName { get; set; }
public string Year { get; set; }
}

Next, we need to add List onto a page or  block, in this example, I’m adding the below code to my start page.

[Display(
Name = "Awards",
Description = "Awards",
GroupName = SystemTabNames.Content,
Order = 10)]
public virtual IList<Award> Awards { get; set; }

If you try and run the site now you will see this error

‘Server Error in ‘/’ Application.

Type ‘System.Collections.Generic.IList`1[[JonDJones.com.Core.Entities.Award, JonDJones.com.Core, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null]]’ could not be mapped to a PropertyDefinitionType’

This is because we need register all List we define with Episerver before it will allow the magic to work. To register a List mapping we need to create a new class to define a property definition. This class will need to inherit from PropertyList

[PropertyDefinitionTypePlugIn]
public class AwardProperty : PropertyList<Award>
{
protected override Award ParseItem(string value)    
{
return JsonConvert.DeserializeObject<Award>(value); 
}     
public override PropertyData ParseToObject(string value)    
{        
ParseToSelf(value);        
return this;    
}  
}

To create a property definition, we create an AwardProperty that inherits from PropertyList. When you inherit from PropertyList you will need to implement, T ParseItem(string value) and PropertyData ParseToObject(string value) . In order to do the ParseItem I’m using JSON.Net.

Production Tip In production code, I would create a generic BaseProperty : PropertyList property.

Like a lot of Episerver properties, we need to decorate the property with an EditorDescriptor to tell Episerver which plug-in definition should be associated with the property, to do that with PropertyList we use an editor descriptor of type CollectionEditorDescriptor.

[Display(
Name = "Awards",
Description = "Awards",
GroupName = SystemTabNames.Content,
Order = 10)]
[EditorDescriptor(EditorDescriptorType = typeof(CollectionEditorDescriptor<Award>))]
public virtual IList<Award> Awards { get; set; }

When we run the code the site will now load. If we look in the CMS we should see the property displayed:

episerver_propertylist_update

If you click the add button, you will see the properties defined in the Award class all displayed and ready to edit.

episerver_propertylist_add

Conclusion

In today’s guide, we’ve talked about List that was released in Episerver 9 and the benefits of using it over blocks. List is a great way to allow on page editing of simple data objects and can make content editors’ lives a bit easier by implementing them.

To get started we need to create a class to define the lists property. We then register a PropertyDefinitionTypePlugIn for that type and register an EditorDescriptor for it.

Jon D Jones

Software Architect, Programmer and Technologist Jon Jones is founder and CEO of London-based tech firm Digital Prompt. He has been working in the field for nearly a decade, specializing in new technologies and technical solution research in the web business. A passionate blogger by heart , speaker & consultant from England.. always on the hunt for the next challenge

More Posts

7 replies
  1. Piotr
    Piotr says:

    Hi!
    This is quite awesome, I’ve been waiting for that funcionality in EPiServer for a long time 🙂
    But I have one problem with that. Let’s say that in Award class I want IList property that is called Pages. When I add it, it seems to be working as when I add new award to a list I am getting a nice editor so I can choose a page for that list for example and then when I click Ok I can see that I have a new item on a list and in a column Pages I can see an ID of that page. Cool! But when I edit the item on the list, I can see only string properties, a list of pages for property IList is empty there. How can I make it work?

    Reply
      • Piotr
        Piotr says:

        Oh, only now I have noticed your reply. No, I am not using anything custom. I forgot to mention that my property that I am talking about is of type IList and I am getting a standard EPiServer editor for that type of property, but still, it seems that it is not fully working, as described in my first comment. I wonder if the problem is in my code or maybe it is an EPiServer bug?

        Reply
    • Jon D Jones
      Jon D Jones says:

      The way you would normally do culture specific data in EpiServer is on a page level not a property level. In the editor, you would have a different version for each culture of a page and EpiServer then renders the correct data based on the users culture. You can set fall back languages so you don’t have to do the whole page translation if you didn’t want to.

      If you need it done on a property level then you are going to get your hands dirty with a custom property and dojo. For your sanity, I would recommend trying to stick to out of the box functionality rather than custom stuff so your working with the CMS instead of against it

      Reply

Trackbacks & Pingbacks

  1. […] How To Render A List Of Objects In a Page Or Block… PropertyList Explained […]

  2. […] EpiServer: How To Render A List Of Objects In a Page Or Block… PropertyList Explained […]

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *