Configuring Rich Text Settings

Introduction

In Optimizely CMS 12 (PaaS), TinyMCE is not merely a visual editing tool - it is a configurable content input system that directly shapes the HTML stored in the CMS database. For developers building structured, scalable, and maintainable solutions, configuring rich text settings is not optional. It is a core architectural decision.

The TinyMCE Configuration API enables developers to control which plugins are available, define toolbar layouts, restrict allowed HTML elements, apply configuration per content type or per property, and extend the editor with custom behaviors.

1. The TinyMCE Configuration Architecture

TinyMCE configuration in CMS 12 is implemented using the ASP.NET Core Options pattern. Implement IConfigureOptions<TinyMceConfiguration>, configure it in the Configure method, and register it in Program.cs:

This pattern ensures configuration is version-controlled, behavior is consistent across environments, and no runtime UI changes affect production unexpectedly. In PaaS deployments this is critical - all configuration changes require a CI/CD promotion.

2. Global vs. Scoped Configuration

The Configuration API supports three levels of scoping. The most specific rule wins.

2.1 Global Configuration

Applies to all XhtmlString properties unless overridden at a more specific scope.

2.2 Content-Type Specific Configuration

Applies to all XhtmlString properties inside a specific content type, overriding the global default.

2.3 Property-Level Configuration

Targets a single specific property on a specific content type - the most granular scope available.

This layered model allows precise editorial control without duplicating configuration across the codebase.

3. Toolbar Configuration

Toolbar configuration defines what editing actions are visible to editors. Toolbar syntax is string-based and follows TinyMCE conventions. The | character creates visual separator groups:

4. Plugin Management

TinyMCE functionality is modular and driven by plugins. Enable plugins using AddPlugin(). Common built-in plugins include lists, link, image, table, code, and paste:

Avoid exposing unnecessary plugins and ensure the toolbar reflects plugin features. Overexposure leads to inconsistent markup, especially in component-based frontend architectures where every authored HTML element must be styled and supported.

5. Default Settings and Valid Elements

CMS 12 ships with default TinyMCE settings governing allowed elements, valid attributes, paste behavior, and formatting rules. Developers can override element validation using AddSetting():

With explicit restrictions, editors cannot insert unsupported tags, stored markup becomes predictable, and frontend rendering remains controlled. Without restrictions, editors may insert markup that conflicts with design systems.

6. Style Formats and Structured Patterns

Predefined style formats let editors apply structured CSS classes without manual HTML editing, bridging editorial freedom with design system enforcement:

Define style formats that map directly to frontend components, avoid generic free-form styling, and pair each format with controlled CSS on the frontend. This is the recommended pattern for component-based architectures.

7. Property-Level Configuration via Attributes

In addition to DI-based configuration, developers can configure individual properties using the [TinyMceSettings] attribute directly on the property:

This approach is localized to a specific property and avoids touching global configuration. However, excessive attribute-level configuration reduces maintainability - in large solutions, centralized DI-based configuration is typically preferred.

8. Paste Behavior and Content Cleanup

TinyMCE includes paste handling capabilities. Developers can configure paste behavior to strip unwanted formatting, remove inline styles, and normalize content pasted from Word or external sources:

Strict paste handling improves content hygiene and reduces unexpected HTML - a particular problem for sites where editors frequently copy from Word, PDFs, or other websites.

9. Security Considerations

Rich text configuration directly impacts application security. TinyMCE limits certain behaviors by default, but developers must ensure valid elements are restricted appropriately, custom plugins do not introduce vulnerabilities, and rendering logic does not bypass CMS sanitization.

• Script injection: Never allow script in valid_elements. Restrict dangerous attributes such as onclick and style at the element level.
• Custom plugins: Custom TinyMCE plugins that accept user input must be reviewed for XSS vulnerabilities before deployment.
• PaaS hardening: Security hardening must be part of code review and CI/CD validation - not a post-deployment fix.

10. Operational Considerations in PaaS

Because CMS 12 PaaS uses structured environment promotion, all TinyMCE configuration changes must be deployed, editorial experience changes must be validated in Integration, and configuration must be backward-compatible with existing content.

• Tightening valid_elements: Previously stored markup may contain tags that the new configuration no longer allows. Migration scripts may be required, and testing across the content repository is recommended before promoting to higher environments.
• Removing plugins: Stored HTML from previously enabled plugins persists in the database regardless of configuration changes. Treat any reduction in editor capabilities as a schema migration requiring a content audit.

Conclusion

Configuring rich text settings in Optimizely CMS 12 is an architectural responsibility. TinyMCE configuration determines what editors can create, what HTML is stored, and how predictable frontend rendering will be. Using the Configuration API, scoped overrides, plugin management, and property-level control, developers can shape a structured, secure, and maintainable editorial experience.

In PaaS environments, these decisions are amplified because configuration is code-driven and deployed through CI/CD pipelines. A deliberate configuration strategy ensures long-term stability, content consistency, and alignment with frontend design systems. Rich text is powerful - but only when controlled intentionally.