TinyMCE configuration API

7 min

Set transformations

If you want to modify the settings object based on the current content, you can do that by registering a SettingsTransform callback for a given property or plugin. You can also remove registered transformations if you know the key. The current settings instance, content, and property name are passed to the callback. The content item can be NULL.

Add a setting transformation

services.Configure<TinyMceConfiguration>(config => {
      var locator = ServiceLocator.Current;
      ...
      config.For<ArticlePage>(t => t.MainBody)
        .AddSettingsTransform("custom", (settings, content, propertyName) => {
          settings["preferred-culture"] = locator.GetInstance<LanguageResolver>().GetPreferredCulture().Name;
        });

      // Remove a specific transform
      config.For<ArticlePage>(t => t.MainBody)
        .RemoveSettingsTransform("custom");
      ...
    }

Add a setting transformation for a plugin

If you are a plugin developer and must run custom initialization code based on the current content item, you should register the transformation callback with your plugin.

services.Configure<TinyMceConfiguration>(config => {
        ...
        
  config.Default()
    .AddPlugin("custom-plugin", (settings, content, propertyName) => {
      settings["custom-plugin-setting"] = content.Id;
     })
     .RemovePlugin("custom-plugin"); // Will remove the plugin and any registered transformations;
     
      config.Default()
        .AddExternalPlugin("custom-external-plugin", "http://url.js", (settings, content, propertyName) => {
           settings["custom-external-setting"] = content.Id;
        });
     ...
 }

Exceptions

If your code throws an exception, the exception is handled, logged, and passed to the client, and an error message is displayed to the user.

Order of execution

If there are transformations registered for plugins and on the setting, the plugin transformation runs first, and then any transformation on the setting. This lets the site developer modify the settings after the plugin developer completes the modifications.

services.Configure<TinyMceConfiguration>(config => {
     ...

      config.Default()
      .AddPlugin("custom-plugin", (settings, content, propertyName) => {
        settings["custom-plugin-setting"] = "plugin value";
      });

      config.Default()
      .AddSettingsTransform("custom-settings", (settings, content propertyName) => {
        settings["custom-plugin-setting"] = "I have modified the plugins settings value";
      });

      ...
    }

Inherit settings from ancestors

To inherit settings from an ancestor, you must set the InheritSettingsFromAncestor property to true. It is set to false by default.

config.InheritSettingsFromAncestor = true

This is a global setting that is applied for types that are configured.

If InheritSettingsFromAncestor is true; Optimizely tries to resolve the setting for a given property starting with the leaf; after that, it traverses upwards in the inheritance hierarchy to find the closest ancestor with a setting for that property. If it cannot be found in the class hierarchy, Default() is used.

Example

Note This property should not be changed by any plug-ins. It should only be used when configuring the site.

abstract class ProductBase {
  public virtual XHtml ProductDescription {
    get;
    set;
  }
}

class ProductPage: ProductBase {}
class ShoeProductPage: ProductPage {}
class ShirtProductPage: ProductPage {}
class BlueShirtProductPage: ShirtProductPage {}
class VerySpecialProductPage: ProductPage {}
class AndEvenMoreSpecialProductPage: VerySpecialProductPage {}

// Init
services.Configure<TinyMceConfiguration>(config => {
      // Enable inheritance of settings
      config.InheritSettingsFromAncestor = true;

      config.Default()
        .Toolbar("epi-image");

      var baseSettings = config.Default().Clone();
      baseSettings
        .AddPlugin("product-selector")
        .Toolbar("product-selector cut paste");

      // Will be applied for every descendants unless they have set a specific setting
      config.For<ProductBase>(t => t.ProductDescription, baseSettings);

      // Will be based on Default() and not the setting configured on the ancestor
      config.For<BlueShirtProductPage>(t => t.ProductDescription)
        .AppendToolbar("color-picker");

      config.For<VerySpecialProductPage>(t => t.ProductDescription, baseSettings)
        .Toolbar("cut past | product-selector | spellchecker);
        });

    /**
     * Page                              Toolbar
     * ==========================================================================
     * ProductPage                       product-select cut paste
     * ShoeProductPage                   product-select cut paste
     * ShirtProductPage                  product-select cut paste
     * BlueShirtProductPage              epi-image | color-picker
     * VerySpecialProductPage            cut paste | product-select | spellchecker
     * AndEvenMoreSpecialProductPage     cut paste | product-select | spellchecker
     **/