Area: Optimizely CMS

ARCHIVED This content is retired and no longer maintained. See the latest version here.

Property settings

Note: This topic has no later version.

Property Settings is a technology to define settings that affects a specific property or property type, for instance how an editor should be configured. The most common example of this is to define settings for the TinyMCE rich-text editor to control which tools should be available when editing a XhtmlProperty.

It has always been possible to define these settings in the administrative interface and as of EPiServer.CMS.UI/EPiServer.CMS.Core 7.16 it is also possible to define settings in code. Since settings can be defined both in code and the administrative interface, similar rules as the ones that controls content types apply. This means that the settings have the following priority:

A specific setting for a property defined in admin view. This can be either a custom settings for this property or pointing to a specific global setting.
A specific setting for a property defined for the model in code.
A global setting defined in admin marked as the “Default” settings for the property type.
A global setting defined in code.

Working with property settings

A typical use case is that the developer is responsible for defining and maintaining the settings but that the administrator has the option to override them, for instance if a tool needs to be added before it is possible to update the website implementation. The workflow could then look as follows:

The developer creates a settings class and sets this as default.
If there is a need to have specific settings for some properties, this is done by creating additional settings classes and add this class as an attribute on the property.
If there is a need for an administrator to change the settings for a specific property they can add a custom setting for the property in the administrative interface. This will take effect immediately.
The settings in admin can be removed once the developers adds this to the code.
If there is a need to change the default settings the administrator can create a new shared setting and mark this as default. This will now take precedence over the default settings from code.
Once the developer has updated the settings from code the default settings in admin can be removed.

Creating a global settings object

The following code sample shows how to create a default settings object and also how to apply personalization for the “administrators” role:

    [ServiceConfiguration(ServiceType = typeof(PropertySettings))]
    public class DefaultTinyMCESettings : PropertySettings<TinyMCESettings>
    {
        public DefaultTinyMCESettings()
        {
            IsDefault = true;
            DisplayName = "Default settings";
            Description = "Default configuration as defined by the developers.";
        }
 
        public override TinyMCESettings GetPropertySettings()
        {
            var settings = new TinyMCESettings();
 
           settings.ToolbarRows.Add(new ToolbarRow(new string[] { TinyMCEButtons.EPiServerLink, TinyMCEButtons.Unlink, TinyMCEButtons.Image,
                                    TinyMCEButtons.EPiServerImageEditor, TinyMCEButtons.Media, TinyMCEButtons.EPiServerPersonalizedContent, 
                                    TinyMCEButtons.Separator, TinyMCEButtons.Cut, TinyMCEButtons.Copy, TinyMCEButtons.Paste, TinyMCEButtons.PasteText,
                                    TinyMCEButtons.PasteWord, TinyMCEButtons.Separator, TinyMCEButtons.Fullscreen }));
          settings.ToolbarRows.Add(new ToolbarRow(new string[] { TinyMCEButtons.Bold, TinyMCEButtons.Italic, TinyMCEButtons.Separator, TinyMCEButtons.BulletedList,                                    TinyMCEButtons.NumericList, TinyMCEButtons.StyleSelect, TinyMCEButtons.Undo, TinyMCEButtons.Redo, TinyMCEButtons.Separator, 
                                    TinyMCEButtons.Search }));
            // Add the default non-visual plugins that replaces built in functionality with EPiServer specifics.
           settings.NonVisualPlugins.Add("advimage");
            settings.NonVisualPlugins.Add("epifilebrowser");
 
            if (PrincipalInfo.CurrentPrincipal.IsInRole("administrators"))
            {
                //Chance to personalize. Let's allow administrators to access the html editor.
                settings.ToolbarRows[1].Buttons.Add("code");
            }
 
            settings.Height = 200;
            settings.Width = 600;
 
            return settings;
        }
 
        public override System.Guid ID
        {
            get { return new System.Guid("a6fe936f-190d-45e2-b83c-ccc0501a7312"); }
        }
    }

Using a custom setting for a property

The following example shows how to apply a custom setting for a specific property by creating a class (in this case the IsDefault property is not set):

    [ServiceConfiguration(ServiceType = typeof(PropertySettings))]
    public class SimpleTinyMCESettings : PropertySettings<TinyMCESettings>
    {
        public SimpleTinyMCESettings()
        {
            DisplayName = "Simple editor";
        }
 
        public override TinyMCESettings GetPropertySettings()
        {
            var settings = new TinyMCESettings();
 
            var mainToolbar = new ToolbarRow(new List<string>() { TinyMCEButtons.Bold, TinyMCEButtons.Italic, TinyMCEButtons.Cut, TinyMCEButtons.Copy, TinyMCEButtons.Paste, TinyMCEButtons.EPiServerLink, TinyMCEButtons.Unlink });
 
            settings.ToolbarRows.Add(mainToolbar);
 
            settings.Height = 20;
            settings.Width = 200;
 
            return settings;
        }
 
        public override System.Guid ID
        {
            get { return new System.Guid("a6fe936f-190d-45e2-b83c-ccc0501a7311"); }
        }
    }

To apply this to a specific property on a model, add the PropertySettings attribute to it as follows:

      [PropertySettings(typeof(SimpleTinyMCESettings))]
      public virtual XhtmlString Sidebar { get; set; }

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

Last updated: Sep 17, 2014