From 6cc96689989a7781f1da4ae05b0fbc38e6c8fdb9 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 29 Jun 2009 03:16:10 +0000 Subject: Add changelog entry for resource directive. Rejigger error detection ordering. --- CHANGES.txt | 74 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) (limited to 'CHANGES.txt') diff --git a/CHANGES.txt b/CHANGES.txt index 4d86a66cb..afb49e1b2 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -4,6 +4,80 @@ Next release Features -------- +- A new ZCML directive exists named "resource". This ZCML directive + allows you to override Chameleon templates within a package (both + directories full of templates and individual template files) with + other templates in the same package or within another package. This + allows you to "fake out" a view's use of a template, causing it to + retrieve a different template than the one actually named by a + relative path to a call like + ``render_template_to_response('templates/mytemplate.pt')``. For + example, you can override a template file by doing:: + + + + The string passed to "to_override" and "override_with" is named a + "specification". The colon separator in a specification separates + the package name from a package-relative directory name. The colon + and the following relative path are optional. If they are not + specified, the override attempts to resolve every lookup into a + package from the directory of another package. For example:: + + + + + Individual subdirectories within a package can also be overridden:: + + + + If you wish to override a directory with another directory, you must + make sure to attach the slash to the end of both the ``to_override`` + specification and the ``override_with`` specification. If you fail + to attach a slash to the end of a specification that points a + directory, you will get unexpected results. You cannot override a + directory specification with a file specification, and vice versa (a + startup error will occur if you try). + + You cannot override a resource with itself (a startup error will + occur if you try). + + Only individual *package* resources may be overridden. Overrides + will not traverse through subpackages within an overridden package. + This means that if you want to override resources for both + ``some.package:templates``, and ``some.package.views:templates``, + you will need to register two overrides. + + The package name in a specification may start with a dot, meaning + that the package is relative to the package in which the ZCML file + resides. For example: + + + + Overrides for the same ``to_overrides`` specification can be named + multiple times within ZCML. Each ``override_with`` path will be + consulted in the order defined within ZCML, forming an override + search path. + + Resource overrides can actually override resources other than + templates. Any software which uses the ``pkg_resources`` + ``get_resource_filename``, ``get_resource_stream`` or + ``get_resource_string`` APIs will obtain an overridden file when an + override is used. However, the only built-in facility which uses + the ``pkg_resources`` API within BFG is the templating stuff, so we + only call out template overrides here. + - Use the ``pkg_resources`` API to locate template filenames instead of dead-reckoning using the ``os.path`` module. -- cgit v1.2.3