From dd88a51c90afc44b55a725610533fa7a958b8218 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Tue, 22 Dec 2009 03:17:57 +0000 Subject: Use roles. --- docs/narr/extending.rst | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) (limited to 'docs') diff --git a/docs/narr/extending.rst b/docs/narr/extending.rst index b82b4d826..c757dde99 100644 --- a/docs/narr/extending.rst +++ b/docs/narr/extending.rst @@ -21,10 +21,11 @@ relying on :term:`configuration decoration` meant to be detected via the a :term:`scan`, and you mustn't configure your :mod:`repoze.bfg` application *imperatively* by using any code which configures the application through methods of the :term:`Configurator` (except for -its ``load_zcml`` method). Instead, should must use :term:`ZCML` for -the equivalent purposes. :term:`ZCML` declarations that belong to an -application can be "overridden" by integrators as necessary, but -decorators and imperative code which perform the same tasks cannot. +the :meth:`repoze.bfg.configuration.Configurator.load_zcml` method). +Instead, should must use :term:`ZCML` for the equivalent +purposes. :term:`ZCML` declarations that belong to an application can +be "overridden" by integrators as necessary, but decorators and +imperative code which perform the same tasks cannot. In general: use only :term:`ZCML` to configure your application if you'd like it to be extensible. @@ -80,8 +81,8 @@ Extending an Application Which Possesses Configuration Decorators Or Which Does ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you've inherited a :mod:`repoze.bfg` application which uses -``@bfg_view`` decorators or which performs configuration imperatively, -one of two things may be true: +:class:`repoze.bfg.view.bfg_view` decorators or which performs +configuration imperatively, one of two things may be true: - If you just want to *extend* the application, you can write additional ZCML that registers more views or routes, loading any @@ -91,13 +92,13 @@ one of two things may be true: - If you want to *override* configuration in the application, you *may* need to change the source code of the original application. - If the only source of trouble is the existence of ``@bfg_view`` - decorators, you can just omit the ```` directive in the - application ZCML. This will cause the decorators to do nothing. At - this point, you will need to convert all the configuration done in - decorators into equivalent :term:`ZCML` and add that ZCML to an a - separate Python package as described in - :ref:`extending_the_application`. + If the only source of trouble is the existence of + :class:`repoze.bfg.view.bfg_view` decorators, you can just omit the + ```` directive in the application ZCML. This will cause the + decorators to do nothing. At this point, you will need to convert + all the configuration done in decorators into equivalent + :term:`ZCML` and add that ZCML to an a separate Python package as + described in :ref:`extending_the_application`. If the source of trouble is configuration done imperatively (perhaps in the function called during application startup), you'll need to -- cgit v1.2.3