Are you tired of wrestling with TYPO3’s RTE (Rich Text Editor) and its seemingly stubborn refusal to respect your carefully crafted TSconfig settings? Specifically, are you frustrated by the inability of the allowedClasses property to have any discernible impact? Fear not, dear developer, for you are not alone in this struggle. In this comprehensive guide, we’ll delve into the mysteries of TYPO3’s RTE, exploring the allowedClasses property, its quirks, and the secrets to making it work as intended.
Understanding the allowedClasses Property
The allowedClasses property is a TSconfig setting that ostensibly allows you to specify a list of permitted HTML classes for elements within the RTE. In theory, this should enable you to control the styling and structure of content created within the editor. However, as many developers have discovered, this property often seems to have little to no effect.
RTE.default {
allowedClasses = my-class,another-class
}
The Problem: Why allowedClasses Fails to Deliver
So, why does the allowedClasses property often fail to work as expected? The primary culprit lies in the way TYPO3’s RTE processes and sanitizes HTML content. By default, the RTE uses a combination of PHP’s `strip_tags()` function and TYPO3’s own `eneralUtility::stripHtmlTags()` method to remove disallowed HTML tags and attributes. This aggressive sanitization can strip away the very classes you’re trying to allow, rendering the allowedClasses property ineffective.
Solving the Enigma: Making allowedClasses Work
To overcome this hurdle, you’ll need to take a multi-pronged approach, involving both TSconfig adjustments and clever usage of the RTE’s built-in features.
Step 1: Relaxing HTML Sanitization
To prevent the RTE from stripping away your allowed classes, you’ll need to relax its HTML sanitization settings. This can be achieved by setting the `RTE.default.proc allowTags` property to include the HTML tags and attributes you need.
RTE.default {
proc {
allowTags = -all, +div, +p, +span, +a, +strong, +em, +u, +sub, +sup
}
}
By allowing these basic HTML tags, you’ll provide the RTE with a more permissive environment, reducing the likelihood of your allowed classes being stripped away.
Step 2: Crafting a Whitelist of Allowed Classes
With the sanitization settings adjusted, it’s time to create a whitelist of allowed classes. This is where the `RTE.default.allowedClasses` property comes into play.
RTE.default {
allowedClasses = my-class, another-class, foo, bar
}
By specifying a list of permitted classes, you’ll enable the RTE to recognize and preserve these classes within the edited content.
Step 3: Defining Class-to-Class Mappings (Optional)
In some cases, you may need to map specific HTML classes to their corresponding TYPO3 classes. This can be achieved using the `RTE.default.classes` property.
RTE.default {
classes {
my-class = my-class
another-class = another-class
}
}
By defining these class-to-class mappings, you’ll ensure that the RTE uses the correct TYPO3 classes when applying styling to your content.
Real-World Examples and Gotchas
To further illustrate the concepts discussed above, let’s consider a few real-world examples and potential gotchas.
Example 1: Allowing a Custom Class for Headings
Suppose you want to allow authors to apply a custom class (`heading-highlight`) to headings within the RTE. To achieve this, you’d need to:
RTE.default {
proc {
allowTags = -all, +h1, +h2, +h3, +h4, +h5, +h6, +span
}
allowedClasses = heading-highlight
}
In this example, we’re allowing the `h1` to `h6` heading tags, as well as the `span` tag, to accommodate the custom class.
Gotcha 1: Overlapping Class Names
Beware of using class names that conflict with existing TYPO3 classes. If you attempt to use a class name already in use by TYPO3, the RTE may produce unexpected results or fail to apply your custom class.
Gotcha 2: Inconsistent Class Application
When using the allowedClasses property, be aware that the RTE may not consistently apply the specified classes to all elements within the content. This can lead to inconsistent styling and layout issues.
Conclusion
In conclusion, the allowedClasses property in TYPO3’s RTE can be a powerful tool for managing content styling and structure, but it requires careful configuration and understanding of the underlying mechanisms. By following the steps outlined in this article, you’ll be well on your way to taming the RTE and unlocking its full potential.
Remember to:
- Relax HTML sanitization settings
- Craft a whitelist of allowed classes
- Define class-to-class mappings (if necessary)
By doing so, you’ll be able to harness the power of the allowedClasses property, bringing order and consistency to your TYPO3 content.
| TSconfig Property | Description |
|---|---|
| RTE.default.allowedClasses | Specifies a list of permitted classes for RTE content |
| RTE.default.proc.allowTags | Controls which HTML tags are allowed or disallowed within the RTE |
| RTE.default.classes | Defines class-to-class mappings for use within the RTE |
We hope this comprehensive guide has provided you with the knowledge and tools necessary to overcome the challenges of working with TYPO3’s RTE and the allowedClasses property. Happy coding!
Frequently Asked Question
Why does the allowedClasses configuration in my TSconfig not work as expected?
It’s possible that the configuration is being overridden by another TSconfig or a third-party extension. Check your entire TSconfig and extension settings to ensure that there are no conflicting configurations.
I’ve checked my TSconfig and extensions, but allowedClasses still doesn’t work. What’s next?
Try clearing the TYPO3 cache and checking the configuration again. Sometimes, a simple cache clear can resolve the issue. If that doesn’t work, you can try debugging the configuration using the TYPO3 Debug Console or a third-party debugging tool.
How do I debug the allowedClasses configuration in TYPO3?
You can use the TYPO3 Debug Console to debug the configuration. Enable the Debug Console in your TYPO3 installation, then navigate to the relevant page and inspect the RTE configuration. Look for any errors or warnings related to the allowedClasses configuration. You can also use the `t3debug` command in the TYPO3 Console to inspect the configuration.
Can I use allowedClasses with custom HTML elements?
Yes, you can use allowedClasses with custom HTML elements. However, you need to ensure that the custom elements are properly registered in the TYPO3 RTE configuration. You can do this by adding the custom elements to the `proc.allowedClasses` configuration in your TSconfig.
What’s the difference between proc.allowedClasses and RTE.default.allowedClasses?
`proc.allowedClasses` is used to specify the allowed classes for a specific processing configuration, whereas `RTE.default.allowedClasses` is used to set the default allowed classes for all RTE instances. You can use both configurations to fine-tune the allowed classes for your TYPO3 installation.
