Node Name Encoding

Overview

In Bloomreach Content, each document and folder in the content repository has two name values:

• Display name: A translatable string intended for presentation, such as breadcrumbs, link labels, page titles, or listings in the CMS.
• Node name: The internal name stored in the repository. The node name is also used by the HST to construct URLs.

Both names are processed using implementations of the org.hippoecm.repository.api.StringCodec interface. This ensures that unsupported characters are either removed or replaced, so that names conform to repository and URL requirements.

For display names, the codec org.hippoecm.repository.api.StringCodecFactory$IdentEncoding is used. This codec returns the input value unchanged.

For node names, the codec org.hippoecm.repository.api.UriEncoding (prior to version 17.1: o.h.r.a.StringCodecFactory$UriEncoding) is used. This codec performs a one-way transformation, converting any UTF-8 string into a set of characters suitable for use in URIs. For detailed encoding behavior, refer to org/hippoecm/repository/api/doc-files/encoding.html in the generated Javadocs.

Configuration

You can configure both codecs in the repository at the following location:

/hippo:configuration/hippo:modules/stringcodec/hippo:moduleconfig

This node contains two properties:

• encoding.display: Specifies the codec for display names.
• encoding.node: Specifies the codec for node names.

Set each property to the fully qualified class name of the desired codec implementation. For example, use org.hippoecm.repository.api.UriEncoding for node names in version 17.1.

Locale-Specific Node Name Encoding

In some scenarios, you may need to encode node names differently depending on the locale. This allows URLs generated by the HST to match the conventions expected by users and systems for a specific language or region. For example, the character 'ä' is typically encoded as 'a', but in German, it should be encoded as 'ae'.

To support locale-specific encoding, you can define additional properties in the configuration:

• For a general language, use encoding.node.<language>, such as encoding.node.de for German.
• For a specific locale, use encoding.node.<language>_<country>, such as encoding.node.de_de for German (Germany) or encoding.node.de_at for German (Austria).

Bloomreach Content provides a default StringCodec implementation. If you require custom encoding logic, you must implement your own StringCodec. Use org.hippoecm.repository.api.UriEncoding (prior to 17.1: o.h.r.a.StringCodecFactory$UriEncoding) as a reference for your implementation.