xsl:character-map

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.

Tip

 

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

Format

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

            

Description

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.

Example

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>
               
 
               
<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>
               
 
               
<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;" />
               
  ...
               
</xsl:character-map>
               

            

 
Free Stylus Studio XML Training:
W3C Member