ECEn XML Web Templates: Troubleshooting

Need help? We understand. Nothing can be so frustrating as to bring up your favorite web browser, expect to see your lovely new webpage, and instead be presented with a blank white screen or an XML parse error. Luckily, there are really only a few common errors people run into when using the ECEn XML Web Templates and they are all fairly easy to fix. Browsing through these troubleshooting pages will help you solve common problems, avoid problems in the future, and report bugs in the template system.

If you’ve run into trouble with ECEn XML Web Templates, browse through some of these problems to see if they might fit your situation. If not, please let the ECEn Web Team know, and we’ll help you resolve the problem.

General Problem Area Symptoms Solution

Broken XML

Finding mis-matched tags

I see the error page:

An error was encountered while parsing the XML file…

Opening and ending tag mismatch

Usually this means you’ve forgotten or misspelled a closing tag. The line numbers on the error message are usually quite helpful in helping you find the missing tag.

To fix the problem:

Find the missing closing tag.

For example, if you see that your <page> and <content> tags are complaining, it should tip you off that you are missing a closing <section> tag somewhere.

But I have so many sections! Using the fact that the <page> and <content> tags are complaining, you know you are missing a <section> tag which is a child of your <content> tag and you don’t need to worry about any of the sections that are children of other sections.

What is a “child tag” in XML? For example, if I create a <section> tag and place a <text> tag within it, then the <text> tag is a child tag of the <section> tag.

Closing <text> tag and <section> tags are the most often forgotten. If you use the free XRAY XML editor, it will notify you as you type your XML file that a tag is missing.

It can also indicate a misspelled closing tag. Remember that XML is case sensitive, so using an uppercase closing tag for a lowercase starting tag would behave just as if the closing tag were missing or misspelled.

Broken XML

‘<’ and ‘&’ run amuk

I see the error page:

An error was encountered while parsing the XML file…

xmlParseEntityRef: no name

Usually this means that you have a stray ‘&’ in your document. This character has special meaning for XML which implies that XML does not treat ‘&’ like a normal text character.

To fix the problem:

Replace ‘&’ with ‘&’ (meaning ampersand).

Broken XML

‘<’ and ‘&’ run amuk

I see the error page:

An error was encountered while parsing the XML file…

StartTag: invalid element name

Usually this means that you have a stray ‘<’ in your document. This character has special meaning for XML which implies that XML does not treat ‘<’ like a normal text character.

To fix the problem:

Replace ‘<’ with ‘<’ (meaning 'less than').

Whitespace between tags, and in general

I see my actual web page, but some of my words don’t have spaces in between them.

So, what’s whitespace? Whitespace is any set of spaces, tabs, line breaks, etc.---any bunch of 'text' that's just empty space.

So, to fix your whitespace problem there are a few things you ought to understand about how the ECEn XML Web Templates handle whitespace:

1	When you are creating content text, special text included, the ECEn XML Web Templates will not guess where you might like whitespace, which means that you must specify your whitespace in every `<text>` and `<special-text>` tag.

If you place several spaces or tabs within text tags, web browsers will generally only render one space, no matter how much whitespace you place within, before or after the text. Even if you add several text tags, with nothing but whitespace within them, you will still only see one space.

If you are spending a lot of time trying to make certain text have whitespace, such as an indent in front, try using a list, or indented sections. Check out the ECEn XML Web Templates Reference.

The issue of collapsing whitespace is not unique to the ECEn XML Web Templates. Most web pages handle whitespace this way thanks to the way HTML handles whitespace. If you need whitespace somewhere and are unable to get it there on your own, please contact the ECEn Web Team and we can probably help.

Broken .phtml files

I see the error page:

An error was encountered while parsing the XML file…

warning: failed to load external entity “index.xml”

Check to make sure your .phtml and .xml files have the same name. The ECEn XML Web Templates use the name of the .phtml file to find its corresponding .xml file. If it isn’t there, your page won’t render.

To fix the problem:

Make sure the .xml and .phtml file have exactly the same name, includeing case (except for the .phtml/.xml extension, of course).

Broken .phtml files

I see a blank, white page.

This probably means there is something wrong with your .phtml file.

To fix the problem:

Try downloading this sample .phtml file, rename it to match your .xml file, and see if that fixes the problem.

Broken .phtml files

I see the error page:

An error was encountered while parsing the XML file…

I/O error: Permission denied

This probably means that the permissions on your XML file are not correct.

To fix the problem:

Make sure that the .xml file is world readable.

If you’re unsure of how to do this, let the ECEn Web Team know, and they’ll be happy to help out.

Hard to read XML files

I see all of the XML on one line with little boxes everywhere.

This probably means you have opened a file in NotePad (Windows) created on Linux/Unix.

This happens because different operating systems record 'newline' characters differently.

To fix the problem:

Open the offending XML file in WordPad.(Right click on the file and from the menu, select 'Open with', and from that menu, select WordPad). Wordpad is usually able to convert the newlines to the Windows format. Without making any changes to the file, save it in WordPad.

You can then close WordPad and open the file in NotePad. The XML file should be easier to read with the linebreaks in place and the boxes gone. Or, if you like, you can continue to work in WordPad.

Missing pieces of web page

Content I specified in an included XML file isn't showing up.

Usually this happens when your XML web page can't find (bad pathname) your included XML file or there is invalid XML within the included XML file.

To fix the problem:

Check the pathname within the <include> tags. Make sure the included XML file is world readable.

If the pathname looks right and the included content still isn't showing up, open up the included XML file. Make sure that the entire chunk of XML within the included file is surrounded by a single outermost tag. If the content is such that there is no outermost tag naturally, enclose all of the XML content within <to-be-included> tags.

If your included XML has an outermost tag, make sure there are no missing or mis-matched opening and closing tags. If you're having a hard time finding your problem, create a .phtml file for your included XML file. Surround the XML in the included file with <page> and <content> tags as you would any normal XML web page. Then look at the page by itself online and use the parse error information to solve the problem. When you're ready to include the file again, be sure to remove the <page> and <content> tags.

You can also try opening the XML file you're trying to include directly in your browser; many of the newer browsers will recognize the file as XML and report general errors (not ECEn XML-specific ones, however) if there are any.