HTML Cleaning

You can clean the contents of HTML fields on both the client side and the server side in Bloomreach Content.

Client-Side HTML Cleaning

CKEditor handles client-side HTML cleaning using its Advanced Content Filter (ACF) feature. The set of allowed HTML elements and attributes depends on the plugins and commands enabled in CKEditor. For example, if the image plugin is not enabled, CKEditor automatically removes <img> tags. The filter also applies to attributes, which you can allow or require as needed.

You can control ACF for each editor instance by setting the [extraAllowedContent](http://docs.ckeditor.com/#!/api/CKEDITOR.config-cfg-extraAllowedContent) configuration property. Starting with brXM 12, you must specify extraAllowedContent in JSON object format. For example:

{
  extraAllowedContent: {q: {}, cite: {classes: 'myclass'}}
}

For more details on ACF and its configuration, refer to the CKEditor documentation.

Disabling Client-Side HTML Cleaning

ACF is enabled by default. To disable ACF, set the CKEditor [allowedContent](http://docs.ckeditor.com/#!/api/CKEDITOR.config-cfg-allowedContent) property to true:

ckeditor.config.overlayed.json:

{
  allowedContent: true
}

Server-Side HTML Cleaning

Server-side HTML cleaning uses an HTML-processor. The HTML-processor checks, cleans, and corrects the output of rich-text fields. It also manages internal links and images. The processor uses an allowlist to define which HTML elements and attributes are permitted. Any attribute not explicitly allowed is removed from the output. Text nodes are always preserved.

By default, server-side cleaning removes the javascript: and data: protocols from <a> href and <object> data attributes for security reasons. You can disable this by setting the omitJavascriptProtocol configuration property to false.

Info:
Starting with brXM 14.3.0, removal of the javascript: and data: protocols applies to all attributes, not just <a> href and <object> data. You can adjust this behavior per element using the omitJavascriptProtocol and omitDataProtocol configuration properties.

Configuration

To configure an HTML-processor for a CKEditor field, set the [htmlprocessor.id](/build/document-types/html-fields-rich-text/html-fields-configuration-properties) property. You can specify this property in the [cluster.options](/build/document-types/html-fields-rich-text/html-fields-configuration-properties) node for a specific document type field, or globally for all formatted and/or rich text fields. The value must match the name of an HTML-processor configuration node in the HTML-processor module:

/hippo:configuration/hippo:modules/htmlprocessor/hippo:moduleconfig

The CMS provides the following default HTML-processor configurations:

  1. formatted: Allowlist for elements used in Formatted fields.
  2. richtext: Allowlist for elements used in Rich Text fields, with internal link and image management.
  3. no-filter: No allowlist, but still manages internal links and images for Rich Text fields.

Each HTML-processor configuration node uses the hipposys:moduleconfig nodetype and supports these properties:

  • charset: Output character set. Default is UTF-8.
  • serializer: Serializer type. Options: pretty, compact, simple. Default is simple.
  • convertLineEndings: Converts CRLF to LF when storing HTML, and vice versa when reading. Default is true.
  • omitComments: Removes comments from HTML. Default is false.
  • omitJavascriptProtocol: Removes JavaScript statements from HTML. Default is true.
  • omitDataProtocol: Removes the data: protocol from HTML. Default is true. Available since 14.3.0.
  • filter: Enables allowlist filtering. Default is true.
  • secureTargetBlankLinks: Adds rel="noopener noreferrer" to external links that open in a new tab or window. See https://web.dev/external-anchors-use-rel-noopener/. Default is true. Available since 14.7.0.
  • allowStyleElements: Allows <style> elements. Default is false, following the HTML5 specification. For configurations with filter=true (such as formatted and richtext), you must also add a "style" subnode to the allowlist. Available since 15.5.0. This restores behavior from before 15.3.0, following an upgrade of the HtmlCleaner library. See the HtmlCleaner release notes.

Allowed HTML elements are defined as child nodes of type hipposys:moduleconfig. The node name matches the allowed element name. Each element node can have a multi-valued attributes property listing the permitted HTML attributes.

Since brXM 14.3.0, you can specify the following options per element:

  • omitJavascriptProtocol: Removes JavaScript statements from HTML for this element. Defaults to the global setting.
  • omitDataProtocol: Removes the data: protocol from HTML for this element. Defaults to the global setting.

The pretty and compact serializers add whitespace to make HTML more readable, which may introduce unwanted spacing with superscript or subscript elements. For this reason, the default serializer is simple.

Disabling Server-Side HTML Cleaning

To disable server-side HTML cleaning, set the [htmlprocessor.id](/build/document-types/html-fields-rich-text/html-fields-configuration-properties) property to no-filter.

Delivery Tier Configuration

HTML cleaning also applies in the delivery tier, including the Page Model API and the default REST API.

Starting with 15.5.0, you can use the htmlcleaner.allowStyleElements option in the HST properties file. The default value is false. Setting this property to true allows <style> elements from HTML fields to appear in API output. This matches the allowStyleElements option in the htmlprocessor module configuration.

This change restores the behavior from before 15.3.0, which was affected by an upgrade to the HtmlCleaner library. For details, see the HtmlCleaner release notes.

Share Feedback
Page: /build/document-types/html-fields-rich-text/html-cleaning
Section: Build
Category *