From e60df41736efca565ce118d4cb6ca0eaced0261f Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 2 Jul 2009 07:37:33 +0000 Subject: - Added a "Resources" chapter to the narrative documentation which explains how to override resources within one package from another package. --- docs/narr/hooks.rst | 77 ----------------------------------------------------- 1 file changed, 77 deletions(-) (limited to 'docs/narr/hooks.rst') diff --git a/docs/narr/hooks.rst b/docs/narr/hooks.rst index 9eba8a92c..086dc16ad 100644 --- a/docs/narr/hooks.rst +++ b/docs/narr/hooks.rst @@ -118,81 +118,4 @@ an object that implements any particular interface; it simply needs have a ``status`` attribute, a ``headerlist`` attribute, and and ``app_iter`` attribute. -.. _overriding_resources_section: - -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