diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/narr/MyProject/MyProject.ini | 1 | ||||
| -rw-r--r-- | docs/narr/project.rst | 15 | ||||
| -rw-r--r-- | docs/narr/templates.rst | 69 | ||||
| -rw-r--r-- | docs/whatsnew-1.3.rst | 10 |
4 files changed, 95 insertions, 0 deletions
diff --git a/docs/narr/MyProject/MyProject.ini b/docs/narr/MyProject/MyProject.ini index 38cbf879c..6741af913 100644 --- a/docs/narr/MyProject/MyProject.ini +++ b/docs/narr/MyProject/MyProject.ini @@ -6,6 +6,7 @@ use = egg:MyProject#app reload_templates = true debug_authorization = false debug_notfound = false +debug_templates = true default_locale_name = en [server:main] diff --git a/docs/narr/project.rst b/docs/narr/project.rst index dfac238b5..97df8a28c 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -233,6 +233,8 @@ section within the ``.ini`` file. For example, if your application reload_templates = true debug_authorization = false debug_notfound = false + debug_templates = true + default_locale_name = en If so, you can use the following command to invoke a debug shell using the name ``main`` as a section name: @@ -279,6 +281,8 @@ following ``.ini`` file content: reload_templates = true debug_authorization = false debug_notfound = false + debug_templates = true + default_locale_name = en [pipeline:main] pipeline = egg:repoze.tm2#tm @@ -534,6 +538,17 @@ detected. See :ref:`reload_templates_section` for more information. production applications, as template rendering is slowed when it is turned on. +The ``debug_templates`` setting in the ``[app:main]`` section is a +:mod:`repoze.bfg` -specific setting which is passed into the +framework. If it exists, and its value is ``true``, :term:`Chameleon` +template exceptions will contained more detailed and helpful +information about the error than when this value is ``false``. See +:ref:`debug_templates_section` for more information. + +.. warning:: The ``debug_templates`` option should be turned off for + production applications, as template rendering is slowed when it is + turned on. + Various other settings may exist in this section having to do with debugging or influencing runtime behavior of a :mod:`repoze.bfg` application. See :ref:`environment_chapter` for more information diff --git a/docs/narr/templates.rst b/docs/narr/templates.rst index 23a1460a1..fc0f38b0f 100644 --- a/docs/narr/templates.rst +++ b/docs/narr/templates.rst @@ -501,6 +501,75 @@ application's configuration section, e.g.:: use = egg:MyProject#app reload_templates = true +.. _debug_templates_section: + +Nicer Exceptions in Templates +----------------------------- + +The exceptions raised by Chameleon templates when a rendering fails +are sometimes less than helpful. :mod:`repoze.bfg` allows you to +configure your application development environment so that exceptions +generated by Chameleon during template compilation and execution will +contain nicer debugging information. + +.. warning:: template-debugging behavior is not recommended for + production sites as it slows renderings; it's usually + only desirable during development. + +In order to turn on template exception debugging, you can use an +environment variable setting or a configuration file setting. + +To use an environment variable, start your application under a shell +using the ``BFG_DEBUG_TEMPLATES`` operating system environment +variable set to ``1``, For example:: + + $ BFG_DEBUG_TEMPLATES=1 bin/paster serve myproject.ini + +To use a setting in the application ``.ini`` file for the same +purpose, set the ``debug_templates`` key to ``true`` within the +application's configuration section, e.g.:: + + [app:main] + use = egg:MyProject#app + debug_templates = true + +With template debugging off, a :exc:`NameError` exception resulting +from rendering a template with an undefined variable +(e.g. ``${wrong}``) might end like this:: + + File "/home/fred/env/lib/python2.5/site-packages/Chameleon-1.2.3-py2.5.egg/chameleon/core/utils.py", line 332, in __getitem__ + raise NameError(key) + NameError: wrong + +Note that the exception has no information about which template was +being rendered when the error occured. But with template debugging +on, an exception resulting from the same problem might end like so:: + + RuntimeError: Caught exception rendering template. + - Expression: ``wrong`` + - Filename: /home/fred/env/bfgzodb/bfgzodb/templates/mytemplate.pt + - Arguments: renderer_name: bfgzodb:templates/mytemplate.pt + template: <PageTemplateFile - at 0x1d2ecf0> + xincludes: <XIncludes - at 0x1d3a130> + request: <Request - at 0x1d2ecd0> + project: bfgzodb + macros: <Macros - at 0x1d3aed0> + context: <MyModel None at 0x1d39130> + view: <function my_view at 0x1d23570> + + NameError: wrong + +The latter tells you which template the error occurred in, as well as +displaying the arguments passed to the template itself. + +.. note:: + + Turning on ``debug_templates`` has the same effect as using the + Chameleon environment variable ``CHAMELEON_DEBUG``. See `Chameleon + Environment Variables + <http://chameleon.repoze.org/docs/latest/config.html#environment-variables>`_ + for more information. + .. index:: single: template internationalization single: internationalization (of templates) diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst index e8f2ddcdd..32964973d 100644 --- a/docs/whatsnew-1.3.rst +++ b/docs/whatsnew-1.3.rst @@ -105,6 +105,16 @@ Minor Feature Additions that user-defined decorators can be defined and found during :mod:`repoze.bfg` scanning. +- It is now possible to turn on Chameleon template "debugging mode" + for all Chameleon BFG templates by setting a BFG-related Paster + ``.ini`` file setting named ``debug_templates``. The exceptions + raised by Chameleon templates when a rendering fails are sometimes + less than helpful. ``debug_templates`` allows you to configure your + application development environment so that exceptions generated by + Chameleon during template compilation and execution will contain + more helpful debugging information. This mode is on by default in + newly generated projects. See also :ref:`debug_templates_section`. + Backwards Incompatibilites -------------------------- |