Error Parsing XHTML: The Content of Elements Must Consist of Well-Formed Character Data or Markup

Problem Context and Error Analysis

In JSF (JavaServer Faces) application development, developers often need to embed JavaScript code within Facelets views to implement client-side interactions. However, when attempting to write JavaScript code containing loop structures within <script> tags, the following error may occur:

javax.servlet.ServletException: Error Parsing /page.xhtml: Error Traced[line:15] The content of elements must consist of well-formed character data or markup.

The root cause of this error lies in the fact that Facelets is an XML-based view technology that uses XHTML+XML to generate HTML output. XML parsers impose strict formatting requirements on document content, particularly in handling five special characters:

• < - Start of tag marker
• > - End of tag marker
• " - Attribute value quotation mark
• ' - Attribute value apostrophe
• & - Start of entity reference

When JavaScript code contains expressions like for (var i = 0; i < length; i++), the XML parser interprets < as the beginning of an XML tag rather than a JavaScript less-than operator. Since the parser expects to find a valid tag name and closing > after <, but instead encounters JavaScript code, it throws a well-formedness error.

Solution 1: Escaping XML Special Characters

The most direct solution is to convert all XML special characters to their corresponding character entity references:

<script type="text/javascript">
function myScript() {
    for (var i = 0; i &lt; length; i++) {
        // Loop body code
    }
}
</script>

In this example, < is replaced with <, allowing the XML parser to correctly recognize it as part of character data rather than the start of a tag. Similarly, other special characters require corresponding escaping:

• > → >
• & → &
• " → "
• ' → '

While this approach solves the problem, it makes JavaScript code difficult to read and maintain, especially when the code contains numerous comparison operations and string concatenations.

Solution 2: Using CDATA Blocks

A more elegant solution involves using CDATA (Character Data) blocks. CDATA blocks instruct the XML parser to treat their contents as pure character data without XML parsing:

<h:outputScript>
    <![CDATA[
        function myScript() {
            for (var i = 0; i < length; i++) {
                // Loop body code
            }
        }
    ]]>
</h:outputScript>

In JSF, the <h:outputScript> component automatically handles CDATA block generation. When using this component, developers can directly write JavaScript code containing XML special characters without manual escaping. The CDATA block syntax ensures that the parser treats all content between <![CDATA[ and ]]> as raw text data.

Solution 3: External JavaScript Files

The best practice is to move JavaScript code to external files and reference them via <script src> or JSF's <h:outputScript> component:

<h:outputScript name="functions.js" target="head" />

In the functions.js file:

function myScript() {
    for (var i = 0; i < length; i++) {
        // Loop body code
    }
}

This approach offers several advantages:

1. Completely avoids XML parsing issues since .js files are not treated as XML documents
2. Improves code maintainability through separation of concerns
3. Allows browser caching of JavaScript files, reducing network transmission
4. Facilitates code reuse and version management

Technical Details and Best Practices

Understanding the distinction between HTML tags and character entities is crucial for solving such problems. In XML documents, strings like <br> appearing in text nodes must be escaped as <br>; otherwise, the parser would interpret them as line break markers. This explains why when discussing HTML tags, we often need to escape them as textual content.

In JSF development, following these best practices can prevent similar parsing errors:

• Place JavaScript code in external files whenever possible
• When scripts must be embedded in Facelets, use the <h:outputScript> component with CDATA blocks
• Avoid using unescaped XML special characters directly in JavaScript strings
• Utilize JSF-provided components rather than raw HTML tags, allowing the framework to handle escaping

By understanding XML parsing mechanisms and the workings of JSF view technologies, developers can effectively avoid errors like The content of elements must consist of well-formed character data or markup and create web applications that comply with XML specifications while remaining maintainable.