Property settings for TinyMCE (Legacy)

📘

Note

This documentation is for version 1 of the TinyMCE add-on only. Documentation for version 2: TinyMCE editor.

📘

Note

In Optimizely Content Management System (CMS) version 11, the TinyMCE editor and related plugin configuration features were moved into a separate NuGet package as an add-on with its own versioning number and breaking changes.

Property settings define settings that affect a specific property or property type, such as 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 in the code and 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 is 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. After the developer adds the settings class to the code, the administrator can remove the settings in the admin view.
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 the code, the administrator can remove the default settings in the admin view.

Create a global settings object

The following code sample shows how to create a default settings object and also how to apply personalization for the administrator's 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");
    }
  }
}

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

Read 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.

Update mergedConfigurationProperties

mergedConfigurationProperties are properties that are mergeable for plugins in TinyMCE. These values are merged if several TinyMCE plugins set different values for any configuration options listed in this attribute.

Default value of mergedConfigurationProperties is: { "valid\_elements", "extended\_valid\_elements", "invalid\_elements", "valid\_child\_elements" }

mergedConfigurationProperties  is an IList, and can be modified in the initialization module, as shown in the following example:

[ModuleDependency(typeof (EPiServer.Web.InitializationModule))]
public class CustomizedTinyMceInitialization: IConfigurableModule {
  public void Initialize(InitializationEngine context) {}

  public void Uninitialize(InitializationEngine context) {}

  public void ConfigureContainer(ServiceConfigurationContext context) {
    context.Services.Configure<EPiServer.Cms.TinyMce.Core.TinyMceOptions>(config => {
      config.MergedConfigurationProperties.Remove("invalid_elements");
    });
  }
}