Property controls

📘

Note

This legacy content applies to Optimizely Content Management System (CMS) versions 10 and 11.

CMS bases rendering on the PropertyControl interface, and the PropertyDataControl base class.

The EPiServer.Web.PropertyControls namespace contains default controls for built-in properties. You can render properties in different ways, but rendering implements IPropertyControl in Web Forms. The property implementation returns the default control by overriding the CreatePropertyControl method from PropertyData.

The abstract base class PropertyDataControl does a lot of the underlying work, so you do not need to inherit from any classes in this namespace when you create custom controls. However, custom controls must inherit from System.Web.UI.Control and implement the EPiServer.Core.IPropertyControl interface. PropertyDataControl has the following more important methods and properties:

Methods

• CreateDefaultControls() – Creates child controls for view mode.
• CreateEditControls() – Creates child controls for edit mode and is valid only for Web Form-based editors.
• ApplyEditChanges() – Saves values from your input controls to the properties and is valid only for Web Forms-based editors.

Properties

• CurrentPage – The current page for the closest parent that implements IPageSource.
• PropertyData – The current property for the control.
• Properties – Returns a PropertyDataCollection with properties that are being edited.
• RenderType – The current RenderType.

📘

Note

You can use several of the methods in PropertyDataControl only when you create a Web Forms-based editor. However, in the default edit view in Optimizely CMS 7 or later, you can use Web Forms-based editing if you configured legacy editing, or if you edit dynamic properties or dynamic content.

Change rendering with PropertyControlBase<T>

If you want to change the rendering of an existing property, perhaps based on a tag, PropertyControlBase<T> lets you use any user control. You also can apply the same method to a WebControl by implementing the IPropertyDataControl<T> interface. A generic implementation of IPropertyControl wraps your control. The following example shows a definition that renders an alternative to PageReference when you use the Testing tag.

[TemplateDescriptor(TagString = "Testing")]
public partial class PropertyControlBaseSample: PropertyControlBase<PageReference> {
  protected void Page_Load(object sender, EventArgs e) {

  }
}

Change rendering for a web browser

If you want to change a property's rendering based on the current request's web browser, map a control adapter using a .browser-file. Because a control adapter inherits from an adapter base class, the EPiServer.Web.PropertyControls.Adapters.PropertyDataControlAdapter base class facilitates the implementation of a custom control adapter for a property. PropertyDataControlAdapter implements many of the properties and methods that exist on PropertyDataControl and redirects the method back to the current PropertyDataControl by default, you can implement the specific methods you want to change the behavior. The following example shows 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();
    Control.Controls.Add(l);
  }
}

📘

Note

You must use Control.Controls.Add() to add a child control in a control adapter. Also, CMS applies control adapters even for inherited classes, so you can apply a PropertyDataControl control adapter to modify the behavior of any control that inherits from PropertyDataControl.

Map presentation of properties with PropertyControlClassFactory

Mapping a PropertyClass through PropertyControlClassFactory overrides which control is used. The following code shows how to map a property to use the second argument (which is required to inherit from Control and implement IPropertyControl), instead of the default control:

EPiServer.Core.PropertyControlClassFactory.Instance.RegisterClass(
  typeof(EPiServer.Core.PropertyNumber),
  typeof(MyNamespace.MyPropertyDataControl));

📘

Note

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