XSLT - Character Maps for Output Customization in XSLT

Character maps are an advanced feature in XSLT that allow developers to automatically replace specific characters or sequences of characters in the final output document. Instead of modifying the source XML or writing additional templates to replace text manually, a character map performs substitutions during the serialization stage, which is the final step where the transformed XML is converted into text, HTML, or XML output.

Character maps are especially useful when you need to generate documents that require special symbols, custom encodings, or reserved characters to appear in a specific format. They help maintain clean transformation logic by separating output formatting from data processing. This makes XSLT stylesheets easier to read, maintain, and reuse.

Why Character Maps Are Needed

During XML transformations, certain characters may need to be displayed differently depending on the target output format. Some systems require special characters to be replaced with predefined text or HTML entities. Writing replacement logic throughout the stylesheet can become repetitive and difficult to maintain.

Character maps solve this problem by defining replacement rules in one location. Whenever the specified character appears in the output, XSLT automatically replaces it according to the mapping.

For example, a copyright symbol can be replaced with the HTML entity ©, or a trademark symbol can be converted into ™ during output generation.

How Character Maps Work

A character map is defined using the <xsl:character-map> element. Inside it, one or more <xsl:output-character> elements specify which character should be replaced and what string should replace it.

The general process is:

  1. XML data is processed normally.

  2. Templates generate the transformed result.

  3. Before writing the final output, XSLT checks for character map rules.

  4. Matching characters are replaced automatically.

  5. The transformed document is produced with customized output.

This approach ensures that replacement occurs only in the final output and does not affect internal XML processing.

Basic Syntax

<xsl:character-map name="myMap">
    <xsl:output-character
        character="©"
        string="&amp;copy;"/>
</xsl:character-map>

<xsl:output method="html"
            use-character-maps="myMap"/>

In this example:

  • A character map named myMap is created.

  • Whenever the copyright symbol appears in the output, it is replaced with &copy;.

  • The character map is attached to the output using the use-character-maps attribute.

Example XML Input

<book>
    <title>XSLT Guide</title>
    <copyright>© 2026</copyright>
</book>

XSLT Transformation

<xsl:stylesheet version="3.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:character-map name="symbols">
    <xsl:output-character
        character="©"
        string="&amp;copy;"/>
</xsl:character-map>

<xsl:output method="html"
use-character-maps="symbols"/>

<xsl:template match="/">
<html>
<body>
<p>
<xsl:value-of select="book/copyright"/>
</p>
</body>
</html>
</xsl:template>

</xsl:stylesheet>

Output

<p>&copy; 2026</p>

Although the XML originally contained the copyright symbol, the final HTML contains the corresponding HTML entity.

Replacing Multiple Characters

A character map can contain multiple replacement rules.

<xsl:character-map name="specialChars">

<xsl:output-character
character="©"
string="&amp;copy;"/>

<xsl:output-character
character="®"
string="&amp;reg;"/>

<xsl:output-character
character="™"
string="&amp;trade;"/>

</xsl:character-map>

If the output contains these symbols, XSLT automatically replaces each one.

Output Example

Original text:

ABC™ Software © 2026 Registered®

Generated output:

ABC&trade; Software &copy; 2026 Registered&reg;

Character Maps with XML Output

Character maps are not limited to HTML output. They can also be used when generating XML or plain text.

Example:

<xsl:output method="xml"
use-character-maps="myMap"/>

This allows customized XML serialization without modifying the original XML content.

Combining Multiple Character Maps

Several character maps can be used together.

<xsl:output
method="html"
use-character-maps="map1 map2"/>

Each map contributes its own replacement rules.

For example:

  • map1 handles currency symbols.

  • map2 handles mathematical symbols.

This modular approach keeps stylesheets organized.

Using Character Maps for Currency Symbols

Suppose an XML document contains various currencies.

Input XML

<prices>
    <amount>₹500</amount>
    <amount>€200</amount>
    <amount>$150</amount>
</prices>

Character Map

<xsl:character-map name="currency">

<xsl:output-character
character="₹"
string="INR "/>

<xsl:output-character
character="€"
string="EUR "/>

<xsl:output-character
character="$"
string="USD "/>

</xsl:character-map>

Output

INR 500
EUR 200
USD 150

The displayed symbols are replaced with standardized currency abbreviations.

Using Character Maps for Mathematical Symbols

Scientific documents often contain mathematical operators.

Original Output

5 ≤ 10
x ≥ y
a ≠ b

Character Map

<xsl:character-map name="math">

<xsl:output-character
character="≤"
string="&amp;le;"/>

<xsl:output-character
character="≥"
string="&amp;ge;"/>

<xsl:output-character
character="≠"
string="&amp;ne;"/>

</xsl:character-map>

Generated HTML

5 &le; 10
x &ge; y
a &ne; b

Advantages of Character Maps

Character maps provide several important benefits:

  • Centralize character replacement rules in one location.

  • Simplify stylesheet maintenance by avoiding repeated replacement logic.

  • Produce output that conforms to HTML, XML, or text formatting requirements.

  • Automatically handle special symbols during serialization.

  • Improve readability and maintainability of XSLT code.

  • Enable consistent formatting across multiple transformations.

  • Reduce the need for custom string manipulation templates.

  • Support modular stylesheet design by allowing multiple character maps.

Limitations of Character Maps

Despite their usefulness, character maps have some limitations:

  • They are applied only during serialization and do not affect internal XML processing.

  • They cannot replace XML elements or attributes; only characters are mapped.

  • Support depends on the XSLT processor being used, particularly for advanced XSLT versions.

  • They are intended for output formatting rather than general text transformation.

  • Complex replacement logic may still require templates or functions.

Best Practices

When using character maps, consider the following guidelines:

  • Keep replacement rules organized by category, such as symbols, currencies, or mathematical operators.

  • Use meaningful names for character maps.

  • Avoid duplicating replacement rules across multiple stylesheets.

  • Test output in different serialization methods, including XML, HTML, and text.

  • Use character maps only for output customization, not for modifying source data.

  • Document replacement rules clearly to simplify maintenance.

Real-World Applications

Character maps are widely used in enterprise XML publishing systems and document transformation workflows. Common applications include:

  • Generating HTML pages with proper HTML entities.

  • Producing XML documents that follow industry-specific formatting standards.

  • Publishing technical manuals containing mathematical symbols.

  • Creating financial reports with standardized currency representations.

  • Generating legal documents with trademark and copyright symbols.

  • Formatting educational content for online learning platforms.

  • Preparing XML for systems that require custom character encodings.

  • Supporting multilingual publishing where special characters must be represented consistently.

Summary

Character maps are a powerful feature in XSLT that simplify output customization by automatically replacing characters during the serialization process. They separate formatting concerns from transformation logic, making stylesheets cleaner, more maintainable, and easier to reuse. By defining centralized replacement rules for symbols, currencies, mathematical operators, and other special characters, developers can produce consistent and standards-compliant output across HTML, XML, and text formats without altering the underlying XML data.