Using the chtml Debugger

There are times when you need to have a closer look how chtml is processing your file to find a problem. The chtml debugger can be used in these cases.

PHP Warning: If you use chtml in your PHP scripts, debug mode may cause strange output because of the way chtml commands remain in the source.

To enable debug mode in a file, place near the top:

<!--chtml options debug-->

If you wish to disable debug mode, you can put into the file:

<!--chtml options nodebug-->

The last of these commands in a file is the one which takes precedence.

To enable debugging for all files in a directory and its subdirectories, place into that directory's .htaccess file:

chtmlDebug on

You can disable debugging with:

chtmlDebug off

The commands used to enable or disable debugging which are placed in a file take precedence over the ones in the .htaccess file.

Warning: The chtmlDebug command only works on the Apache 2.x servers (the new Linux servers). Until the transition is complete, you can use this command to enable debugging which will work on both servers:


Debugging output

When using the chtml debugger, all chtml commands will remain in the source, marked with a status. For example:

Original HTML<!--chtml date="%d-%b-%Y"-->
Without Debugger20-Jun-2008
With Debugger<!--chtml-OK date="%d-%b-%Y"-->20-Jun-2008

Included files will also show the full path to the file as well as where the file begins and ends. This helps to pick out nested include files:

test.incContents of <!--chtml include ""-->
test2.incContents of nested include file
Original HTML<!--chtml include ""-->
Without DebuggerContents of Contents of nested include file
With Debugger<!--chtml-OK include "" START /www/world/webinfo/chtml/>Contents of <!--chtml-OK include "" START /www/world/webinfo/chtml/>Contents of nested include file <!--chtml-OK END /www/world/webinfo/chtml/> <!--chtml-OK END /www/world/webinfo/chtml/>

While it may seem difficult at first to read this output, it's best to work from the inside out. Each START/END pair shows the filename which is being included, and the output shows that code> is included from within

The debugger also shows information about files which could not be included. For example:

Original HTML<!--chtml include ""-->
Without Debugger
With Debugger<!--chtml-FAILED include "" file="/www/world/webinfo/chtml/" error="No such file or directory"-->

If the error is Permission denied, then either the file is unreadable or one of its parent directories is unreadable. This normally should only happen in the wwwdev or wwwudev environments.