Add custom settings to your editor

We learned in previous parts how property editors work, how to write a custom editor, a widget for the editor, and how to test it.

In this part, we will learn how to add custom settings to your editor, located right below the editor select box in the Entry Template Designer tool. It looks like this: (remember, in our current version there is nothing)

Settings are part of the the editorConfig you are injecting in the ControlRegistry object (ControlRegistry.editors.editorConfigs array). The config can have a settings property, which is an array of object defining the settings. Here is how it looks like:

ControlRegistry.editors.editorConfigs[editorId] = {
    label: "My Custom Editor",
    editorClass: MyCustomEditor,
    settings: [
        {
            name: "aCustomSetting",
            controlClass: TextBoxSetting,
            controlParams: {
                label: "A Custom Setting",
                help: "Some Help for this setting"
            }
        },
        {
            name: "aCustomSetting2",
            controlClass: TextBoxSetting,
            controlParams: {
                label: "Another Custom Setting",
                help: "Some Help for this setting"
            }
        },
        {
            name: "aCustomBooleanSetting",
            controlClass: CheckBoxSetting,
            controlParams: {
                label: "Some boolean setting",
                help: "Don't do it!"
            }
        }
        //add more settings if you need
    ]
};

The name is the attribute name in the object, the controlClass is the class used as Editor, They are from the pvd/widget/designer/settings package, here is a list of what’s available:

• CheckBoxSetting
• DimensionSetting
• EditorSetting
• HiddenSetting
• NumberTextBoxSetting
• PatternSetting
• SelectSetting
• StaticTextSetting
• TextareaSetting
• TextBoxSetting

You could create your own but that’s another topic, and they are just settings so I guess that should be enough 😉

So let’s add these settings to our custom editor: update the CustomEditorPlugin.js file to inject the new configuration including the settings. The new code looks like this:

require([
    "dojo/_base/lang",
    "ecm/model/configuration/ControlRegistry",
    "pvd/widget/designer/settings/TextBoxSetting",
    "pvd/widget/designer/settings/CheckBoxSetting",
    "customEditorPluginDojo/editors/MyCustomEditor" // our custom editor widget
], function(
    lang, ControlRegistry, TextBoxSetting, CheckBoxSetting, MyCustomEditor
) {
    var editorId = "myCustomEditor";

    ControlRegistry.editors.editorConfigs[editorId] = {
        label: "My Custom Editor",
        editorClass: MyCustomEditor,
        settings: [
            {
                name: "aCustomSetting",
                controlClass: TextBoxSetting,
                controlParams: {
                    label: "A Custom Setting",
                    help: "Some Help for this setting"
                }
            },
            {
                name: "aCustomSetting2",
                controlClass: TextBoxSetting,
                controlParams: {
                    label: "Another Custom Setting",
                    help: "Some Help for this setting"
                       }
                   },
                   {
                name: "aCustomBooleanSetting",
                controlClass: CheckBoxSetting,
                controlParams: {
                    label: "Some boolean setting",
                    help: "Don't do it!"
                }
            }
        ]
    };

    ControlRegistry.editors.mappings.types["string"].single.editorConfigs.push(editorId);
});

If you refresh (and empty your cache as always, you have nice add-ons for Chrome and Firefox to do both in one click), you should now see that when you’re selecting your custom editor, your settings appear below the select!

Put some values in it and we will now check how they are available in your editor.

If you debug ICN javascript code when adding a new document using our entry template, you can notice that they are stored as field of the widget class:

So that means when you are adding settings, you can use them as normal fields in your editor. Let’s update our code to make use of our checkbox: add the following function to the MyCustomWidget class:

postCreate: function () {
    if (this.aCustomBooleanSetting) {
        this.inputField.set('value', 'Oh no! You did it!');
    }
}

And make sure you’ve checked the checkbox when configuring the entry template. Reload everything, add a new document using our entry template, and you should see this:

I know, that’s a dummy example. But from here you can have all sort of settings of all sort of types. That means you can have one custom editor heavily configurable to fit all sort of usages!

Next part will be about writing a more complex widget.