From 71622f50d19802660cf54b833341db0af72753e6 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 29 Jun 2009 03:19:03 +0000 Subject: Add to docs. --- docs/narr/hooks.rst | 76 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) (limited to 'docs') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index dab8eaad7..8455a6b04 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -118,3 +118,79 @@ an object that implements any particular interface; it simply needs have a ``status`` attribute, a ``headerlist`` attribute, and and ``app_iter`` attribute. +Overriding Resources +-------------------- + +A 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. + -- cgit v1.2.3