Declares a character map defined by a unique name. A stylesheet cannot contain two or more character maps with the same name. Character maps are supported by XSLT 2.0 only.



Character maps are an alternative to defining character entities using a DTD, which was required by XSLT 1.0.


  name = qname
  [use-character-maps = qnames]>
  [<xsl:output-character> ...]



A character map allows a specific character appearing in a text or attribute node in the final result tree to be substituted by a specified string of characters during serialization. The character map that is supplied as a parameter to the serializer is determined from the xsl:character-map elements referenced from the xsl:output declaration for the selected output definition.

Character/string mappings can be defined in the body of the xsl:character-map element using one or more xsl:output-character elements, or they can be defined in an external character map referenced using the optional use-character-maps attribute. If the character map references multiple external character maps, separate each character map's Qname with a space.

An output definition, after recursive expansion of character maps referenced via its use-character-maps attribute, may contain several mappings for the same character. In this situation, the last character mapping takes precedence.

If a character is mapped, it is not subjected to XML or HTML escaping.


This example shows a composite character map - one constructed using both internally defined character mappings ( xsl:output-character), and references to externally defined character maps (the use-character-maps attribute):

<xsl:output name="htmlDoc" use-character-maps="htmlDoc" />
<xsl:character-map name="htmlDoc"
  use-character-maps="html-chars doc-entities windows-format" />
<xsl:character-map name="html-chars"
  use-character-maps="latin1 ..." />
<xsl:character-map name="latin1">
  <xsl:output-character character="&#160;" string="&amp;nbsp;" />
  <xsl:output-character character="&#161;" string="&amp;iexcl;" />
<xsl:character-map name="doc-entities">
  <xsl:output-character character="&#xE400;" string="&amp;t-and-c;" />
  <xsl:output-character character="&#xE401;" string="&amp;chap1;" />
  <xsl:output-character character="&#xE402;" string="&amp;chap2;" />
<xsl:character-map name="windows-format">
  <!-- newlines as CRLF -->
  <xsl:output-character character="&#xA;" string="&#xD;&#xA;" />
  <!-- tabs as three spaces -->
  <xsl:output-character character="&#x9;" string="   " />
  <!-- images for special characters -->
  <xsl:output-character character="&#xF001;"
    string="&lt;img src='special1.gif' /&gt;" />
  <xsl:output-character character="&#xF002;"
    string="&lt;img src='special2.gif' /&gt;" />


Free Stylus Studio XML Training:
W3C Member