SaaS CMS has officially launched! Learn more now.

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 release SaaS CMS

Discover the future of content management with Optimizely SaaS CMS. Enjoy seamless updates, reduced costs, and enhanced flexibility for developers...

Andy Blyth | Jul 17, 2024 | Syndicated blog

A day in the life of an Optimizely Developer - London Meetup 2024

Hello and welcome to another instalment of A Day In The Life Of An Optimizely Developer. Last night (11th July 2024) I was excited to have attended...

Graham Carr | Jul 16, 2024

Creating Custom Actors for Optimizely Forms

Optimizely Forms is a powerful tool for creating web forms for various purposes such as registrations, job applications, surveys, etc. By default,...

Nahid | Jul 16, 2024

Optimizely SaaS CMS Concepts and Terminologies

Whether you're a new user of Optimizely CMS or a veteran who have been through the evolution of it, the SaaS CMS is bringing some new concepts and...

Patrick Lam | Jul 15, 2024