Linus Ekström
Jan 16, 2014
(4 votes)

Editing complex properties

In this post I’ll show how to create editors for complex properties in EPiServer. With complex properties I am referring to block properties that have several sub properties. For this blog post, I’ll be using the ButtonBlock of the Alloy Template package:

public class ButtonBlock : SiteBlockData
    public virtual string ButtonText { get; set; }
    public virtual Url ButtonLink { get; set; }


When the editing system in EPiServer scaffolds the meta data used to create the editor form we recursively go through the object graph until we find an object type with a registered editor. By default, this would mean that we would not find an editor for the ButtonBlock type and therefore go down to the properties for the type, in this case string and Url which both has editor descriptors registered. Let us add an editor descriptor for ButtonBlock to take over editing the entire block:

[EditorDescriptorRegistration(TargetType = typeof(ButtonBlock))]
public class ButtonBlockEditorDescriptor : EditorDescriptor
    public ButtonBlockEditorDescriptor()
        ClientEditingClass = "alloy/editors/ButtonBlockEditor";


We’ll also add a simple editor widget

function (
) {
    return declare([_Widget, _TemplatedMixin, _WidgetsInTemplateMixin], {
        templateString: "<div class=\"dijitInline\">\
                           <div data-dojo-attach-point=\"buttonText\" data-dojo-type=\"dijit/form/ValidationTextBox\"></div>\
        value: null,
        onChange: function (value) {
            // Event to trigger updates
        postCreate: function () {
            // call base implementation
            // Init textarea and bind event
            this.own(this.buttonText.on("change", lang.hitch(this, "_onTextAreaChanged")));
        // Event handler to trigger saving complex value
        _onTextAreaChanged: function (value) {
            var newValue = {
                buttonText: value,
                buttonLink: Date().toLowerCase()
            this.value = newValue;


The Button Block editor looks like this:


Though the example above doesn’t really make any sense, it shows how you can create an editor for a complex object and setting the value to a complex object (in this case just auto-populating the buttonLink value to a date and time). If you want to create an editor that actually does something useful you would probably have to add some more input widgets to the editor and combine the values from the different fields. This also means that you will have to layout the sub fields to fix nicely to the form. Though surely possible, it raises the complexity and amount of work quite a lot. Given the block mentioned above for instance, you need to know how an URL is edited in EPiServer.

Extending the FormContainer

In many cases, you don’t want to control how the sub editors are created. You just want to attach events and logic so that several widgets are bound to each other. For instance:

  • Hide/show a widget depending on another widgets value.
  • Clear the value of a property when another property changes.
  • Populate a drop down with certain values depending on the values of another property.

This can be done by inheriting from "epi/shell/widget/FormContainer" and attaching event handlers to the onFieldCreated and onFormCreated events. Let’s look at an example:

function (
) {
    return declare([FormContainer], {
        onFieldCreated: function (fieldName, widget) {
            this[this.getIndexSecurePropertyName(fieldName)] = widget;
        onFormCreated: function () {
            var textWidget = this[this.getIndexSecurePropertyName("buttonText")];
            var linkWidget = this[this.getIndexSecurePropertyName("buttonLink")];
            this.own(linkWidget.on("change", lang.hitch(this, function (newValue) {
                if (!newValue) {
                    textWidget.set("value", "");
        getIndexSecurePropertyName: function (propertyName) {
            return "prefix-" + propertyName;


And the editor now looks the same as in the default Alloy templates:


We are basically doing two things in this widget:

  1. We store a reference for each sub widget with the property name in the onFieldCreated event.
  2. In inFormCreated we attach an event handler to the linkWidget’s changed event and clear the textWidget if the new link value is empty. (Don’t forget to “own” the event handler so that the widget destroys this when the widget is destroyed so that we don’t get a memory leak)

Note: For the sample above I noticed that the “change” event is not triggered when adding a link through drag and drop or when removing a link through clicking on the (x) next to an existing link. I have added a bug report for this.

Solving the dependent drop down case could be done by calling a custom method on a widget, for instance a “populateDropDown” method with the value from another widget but I will not go into more detail in this blog post.

My colleague Duong an Nguyen has written a more detailed sample with a similar but slightly different approach that you probably want to read as well:

Jan 16, 2014


Please login to comment.
Latest blogs
Optimizely Web Experimentation Metrics

Within the domain of Optimizely Web Experimentation Metrics, the emphasis is on objective key performance indicators (KPIs) selected to assess an...

Matthew Dunn | Sep 23, 2023 | Syndicated blog

Optimizely For you Intranet

Having been at Optimizely and in the CMS industry for nearly 16 years I have seen clients’ intranet requirements go from a simple site just to hous...

Robert Folan | Sep 22, 2023

Vulnerability in EPiServer.GoogleAnalytics v3 and v4

Introduction A potential security vulnerability was detected for Optimizely Google Analytics addon (including EPiServer.GoogleAnalytics and...

Bien Nguyen | Sep 20, 2023

Overriding Optimizely’s Content Recommendations Block to Implement Custom Recommendations

Introduction The Content Recommendations add-on for Optimizely CMS dynamically recommends content from your site tailored to the interests of each...

abritt | Sep 13, 2023 | Syndicated blog

Developer contest! Install the AI Assistant and Win Bose QC45 Headphones!

We are thrilled to announce a developer contest where you have the chance to win a pair of Bose Headphones. The goal is to be the first developer t...

Luc Gosso (MVP) | Sep 7, 2023 | Syndicated blog

Send Optimizely notifications with SendGrid API, not SMTP

If your Optimizely site already sends transaction emails through an email platform API, why not do the same with Optimizely notification emails?

Stefan Holm Olsen | Sep 6, 2023 | Syndicated blog