If you use Cheetah, please support the project and register by clicking here:


10.2 #errorCatcher and ErrorCatcher objects

Syntax:

#errorCatcher CLASS
#errorCatcher $PLACEHOLDER_TO_AN_ERROR_CATCHER_INSTANCE

ErrorCatcher is a debugging tool that catches exceptions that occur inside $placeholder tags and provides a customizable warning to the developer. Normally, the first missing namespace value raises a NameMapper.NotFound error and halts the filling of the template. This requires the developer to resolve the exceptions in order without seeing the subsequent output. When an ErrorCatcher is enabled, the developer can see all the exceptions at once as well as the template output around them.

The Cheetah.ErrorCatchers module defines the base class for ErrorCatchers:

class ErrorCatcher:
    _exceptionsToCatch = (NameMapper.NotFound,)
    
    def __init__(self, templateObj):
        pass
    
    def exceptions(self):
        return self._exceptionsToCatch
    
    def warn(self, exc_val, code, rawCode, lineCol):
        return rawCode

This ErrorCatcher catches NameMapper.NotFound exceptions and leaves the offending placeholder visible in its raw form in the template output. If the following template is executed:

#errorCatcher Echo
#set $iExist = 'Here I am!'
Here's a good placeholder: $iExist
Here's bad placeholder: $iDontExist

the output will be:

Here's a good placeholder: Here I am!
Here's bad placeholder: $iDontExist

The base class shown above is also accessible under the alias Cheetah.ErrorCatchers.Echo. Cheetah.ErrorCatchers also provides a number of specialized subclasses that warn about exceptions in different ways. Cheetah.ErrorCatchers.BigEcho will output

Here's a good placeholder: Here I am!
Here's bad placeholder: ===============<$iDontExist could not be found>===============

ErrorCatcher has a significant performance impact and is turned off by default. It can also be turned on with the Template class' 'errorCatcher' keyword argument. The value of this argument should either be a string specifying which of the classes in Cheetah.ErrorCatchers to use, or a class that subclasses Cheetah.ErrorCatchers.ErrorCatcher. The #errorCatcher directive can also be used to change the errorCatcher part way through a template.

Cheetah.ErrorCatchers.ListErrors will produce the same ouput as Echo while maintaining a list of the errors that can be retrieved later. To retrieve the list, use the Template class' 'errorCatcher' method to retrieve the errorCatcher and then call its listErrors method.

ErrorCatcher doesn't catch exceptions raised inside directives.

If you use Cheetah, please support the project and register by clicking here: