Enhancing Umbraco RTE Configurations: Combining Stylesheets and AppSettings for Flexibility

  • Date : Tuesday, December 31, 2024
  • | Categories : Umbraco 13
  • | Read Time

In Umbraco, styling for the Rich Text Editor (RTE) can be applied using RTE styles, allowing you to define your own dropdown options. See the documentation for more details.

While this feature is great, it has some limitations:

  • You can't easily limit specific options.
  • RTE styles cannot be grouped, which can be a drawback for larger websites.

Alternatively, you can configure styles via the appsettings.json file. See the Rich Text Editor settings documentation. However, this approach requires escaping the configuration manually, reducing its readability.

To address this, you can use the Umbraco.Community.RTEStyleFormatter plugin, available in the marketplace. This plugin simplifies the process of managing RTE styles by allowing you to define them more effectively.

However, one drawback is that the plugin stores its files in the App_Plugins folder, which feels more like configuration than an Umbraco extension.

Combining Stylesheets and AppSettings

In earlier versions of Umbraco, you could combine stylesheets and appsettings to define RTE styles, but this is no longer supported in Umbraco 12 and later. See GitHub issue #13582, which highlights:

  • The inability to mix and match RTE styles and appsettings.
  • Limitations when using the stylesheet variant or appsettings individually.

For example, using stylesheets to define attributes like:

/**umb_name:H2*/
h2 {
	font-size: 24px;
	font-weight: bold;
}

allowed for visual styling in the RTE while combining appsettings for additional functionality, such as defining list types. However, this combination no longer works, forcing a choice between stylesheets or appsettings.

Workaround

You can still use stylesheets to define colors and visual styles while omitting the Umbraco-specific attributes (e.g., /**umb_name:H2*/). This allows the colors to display in the RTE but applies configurations via the appsettings.json file instead. This workaround enables:

  • More options in the RTE.
  • Better grouping of styles, improving clarity for users.

Here’s an example configuration for appsettings.json:

"RichTextEditor": {
  "CustomConfig": {
    "style_formats": "[{\"title\":\"Checked List\", \"selector\": \"ul\", \"classes\": \"list list-check\" },{\"title\":\"Numbered List\", \"selector\": \"ol\", \"classes\": \"list list-decimal\" },{\"title\":\"Heading Link\", \"selector\": \"a\", \"classes\": \"link-heading\" }]"
  }
}

By separating stylesheets for colors and defining other attributes in appsettings.json, you can achieve a more flexible and user-friendly RTE setup.

 

RTE Dropdown

Enhancing Readability with JSON Files

To simplify the configuration, you can store the JSON for RTE styles in a separate file and link it to the appsettings dynamically. Below is a C# extension method to handle this:

using System.Text.Json;

namespace Umbraco.Website.Extensions
{
    public static class IConfigurationExtensions
    {
        /// <summary>
        /// Updates Umbraco RTE style formats from a JSON file.
        /// </summary>
        public static async void UpdateUmbracoRteStyleFormats(
            this IConfiguration config,
            string pathToUmbracoRtfStyleFormatsJsonFile
        )
        {
            const string UmbracoRteStyleFormatsKey =
                "Umbraco:CMS:RichTextEditor:CustomConfig:style_formats";

            if (config is null) throw new ArgumentNullException(nameof(config));
            if (pathToUmbracoRtfStyleFormatsJsonFile is null) throw new ArgumentNullException(nameof(pathToUmbracoRtfStyleFormatsJsonFile));

            using var reader = new StreamReader(pathToUmbracoRtfStyleFormatsJsonFile);
            var rteStyleFormatsJson = await JsonDocument.ParseAsync(reader.BaseStream);

            var rteStyleFormatsAsString = JsonSerializer.Serialize(rteStyleFormatsJson);
            config[UmbracoRteStyleFormatsKey] = rteStyleFormatsAsString;
        }
    }
}

Format Parameters for appsettings.json

When defining RTE styles in appsettings.json, you can specify additional parameters to control how they are applied. These parameters provide flexibility in how elements are styled in the RTE.

Parameter Summary
inline Tag name of the inline element to use as a wrapper, e.g., "span" to wrap the current selection.
block Tag name of the block element to use as a wrapper, e.g., "h1". Replaces existing block elements.
selector CSS3 selector pattern to find elements within the selection, e.g., applying classes to odd table rows.
classes Space-separated list of classes applied to the selected or newly created inline/block element.
styles Key/value object with CSS styles (e.g., color, backgroundColor, textDecoration) to apply.
attributes Key/value object with attributes to apply to the selected or newly created inline/block element.
exact Ensures the format is not merged with other wrappers having the same format, avoiding conflicts.
wrapper Indicates the format is a container for block elements, e.g., a div wrapper or blockquote.

These parameters allow for precise control over how RTE styles are applied, making it possible to create highly customized and user-friendly editing experiences. By leveraging these settings, you can streamline your RTE setup while maintaining flexibility for various use cases.

This solution provides:

  • A workaround to combine stylesheet colors with appsettings for enhanced flexibility.
  • A method to dynamically update RTE styles from a JSON file, improving readability and maintainability.

By implementing this approach, you can overcome the limitations introduced in Umbraco 12 and above, offering a cleaner and more flexible way to manage RTE configurations.

Note

For Umbraco 15+ the TinyMCE editor is replaced by TipTap. The Tiptap UI currently does not support using custom styles for your rich text.

See TipTap Editor