Area: Optimizely CMS
ARCHIVED This content is retired and no longer maintained. See the latest version here.

Recommended reading 

Properties are rendered in different context but under the covers it is always a control implementing IPropertyControl in Web Forms, the default control is returned by the property implementation by overriding the method CreatePropertyControl from PropertyData . This is an introduction to different ways you can change rendering of properties.

Property controls

The namespace EPiServer.Web.PropertyControls contains all the default controls for the built-in properties. The abstract base class PropertyDataControl does a lot of the underlying work, lessening the burden for developers creating custom controls. There is no need to inherit from any classes in this namespace. The only thing required is for custom controls to inherit from System.Web.UI.Control and implement the EPiServer.Core.IPropertyControl interface.

Some of the more important methods and properties on PropertyDataControl include:

Method Description
CreateDefaultControls() Used to create child controls for view mode.
CreateEditControls() Used to create child controls for edit mode. This is only valid for web form based editors.
ApplyEditChanges() Used to save values from your input controls to the property/properties. This is only valid for web form based editors

Property Description
CurrentPage The current page for the closest parent that implements IPageSource.
PropertyData The current property for the control.
Properties Returns a PropertyDataCollection with all properties that are being edited.
RenderType The current RenderType.
Several of the methods in PropertyDataControl are only used when creating web forms based editors which is not the case for the default edit view in EPiServer 7 or later. Web forms based editing is used if you have configured legacy editing, or when editing dynamic properties or dynamic content.

Using PropertyControlBase<T> to change rendering

If you just want to change rendering of an existing property, perhaps based on a tag you can use the PropertyControlBase<T> that allows you to use any user control. The same method can also be applied to a WebControl by implementing the interface IPropertyDataControl<T> yourself. Under the covers your control is being wrapped by a generic implementation of IPropertyControl. Example definition that renders an alternative to PageReference when tag "Testing" is being used.

public partial class PropertyControlBaseSample : PropertyControlBase<PageReference>
    protected void Page_Load(object sender, EventArgs e)


Using control adapters for properties

If you want to change rendering of a property depending on the web browser of the current request you can map a control adapter using a .browser-file . Since a control adapter has to inherit from an adapter base class EPiServer CMS has a base class called EPiServer.Web.PropertyControls.Adapters.PropertyDataControlAdapter to facilitate implementation of a custom control adapter for a property. PropertyDataControlAdapter implements many of the properties and methods that exist on PropertyDataControl and the default behavior is to redirect the method back to the current PropertyDataControl. This makes it a simple task to implement the specific methods that you want to change the behavior for. Following is a simple example of a control adapter that overrides the default behavior for EPiServer.Web.PropertyControls.PropertyLongStringControl :

public class PropertyLongStringControlAdapter : PropertyDataControlAdapter
        public override void CreateDefaultControls()
            Label l = new Label();
            l.Text = PropertyData.ToString();
Note that you have to use Control.Controls.Add() when you want to add a child control in a control adapter. Also note that control adapters are applied even for inherited classes. This means that the behavior of any control inheriting from PropertyDataControl is open for modification by applying a control adapter for PropertyDataControl.

Mapping presentation of properties through PropertyControlClassFactory

It's also possible to override what control should be used by mapping a PropertyClass through PropertyControlClassFactory. The following code shows how to map a property so that the second argument, that is required to inherit from Control and implement IPropertyControl, is used instead of the default control:

PropertyMappings are not applied recursively for child classes. This means that PropertyXhtmlString will still have its default PropertyControl even though you map PropertyLongString.

Do you find this information helpful? Please log in to provide feedback.

Last updated: Mar 31, 2014

Recommended reading