This content is archived. See latest version here

Last updated: Feb 23 2015

Property settings

Property Settings defines settings that affect a specific property or property type, such as how to configure 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 administrative interface. Rules similar to the ones that control content types apply, so the 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.

A typical use case is a developer who is responsible for defining and maintaining settings and an administrator who can override the setting. For example, if you need to add a tool before you can update 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 settings classes and adds this class as an attribute on the property.
  3. If an administrator needs to change the settings for a specific property, the administrator adds a custom setting for the property in the administrative interface, which takes immediate effect.
  4. The administrator can remove the settings in the admin view after the developers add the settings class to the code.
  5. If an administrator needs to change the default settings, the administrator 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 [New in 8.5]

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 have feedback on this documentation? Send an email to documentation@episerver.com. For development-related questions and discussions, refer to our Forums on https://world.episerver.com/forum/