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

Back to top