AI OnAI Off
Loading...
Area: Optimizely CMS
ARCHIVED This content is retired and no longer maintained. See the latest version here.

Recommended reading 

Property settings

Property Settings define settings that affect a specific property or property type, for example, how an editor is configured. A common example is to define settings for the TinyMCE rich-text editor to control which tools are available when editing an XhtmlString property type.

You can define settings both in code and in the admin view. Rules similar to ones that control content types apply, so settings have the following priorities:

  1. A specific setting for a property defined in the admin view, which is either a custom setting for this property or a pointer to a specific global setting.
  2. A specific setting for a property defined for the model in code.
  3. A global setting defined in the admin view marked as the Default settings for the property type.
  4. A global setting defined in code.

Typical use cases are: a developer responsible for defining and maintaining settings, and an administrator who can override the settings. For example, if you need to add a tool before updating the website implementation, the workflow may look as follows:

  1. The developer creates a settings class and sets this as default.
  2. If the developer needs specific settings for some properties, the developer creates a settings class and adds it as an attribute on the property.
  3. If an administrator needs to change settings for a specific property, he adds a custom setting for the property in the admin view, which takes immediate effect.
  4. The administrator can remove the settings in the admin view after the developer add the settings class to the code.
  5. If an administrator needs to change the default settings, he creates a shared setting and marks this as the default to take precedence over the code's default settings.
  6. After the developer updates the settings from code, the administrator can remove the default settings in the admin view.

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; }

Reading a custom setting for a property

If you are developing a custom property, you can read the property setting using an extension method on content, as shown in the following example:

var settings = page.GetPropertySettings<TinyMCESettings, PageWithPropertySettings>(p => p.Sidebar);
You can use the underlying the PropertySettingsResolver class to read property settings without having access to a typed model.
Do you find this information helpful? Please log in to provide feedback.

Last updated: Sep 21, 2015

Recommended reading