From e1a7e0679759da628676f3c73c34875e9b2b6a43 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 26 Dec 2010 01:13:26 -0500 Subject: - Move ZCML usage in Hooks chapter to Declarative Configuration chapter. --- docs/narr/declarative.rst | 140 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 137 insertions(+), 3 deletions(-) (limited to 'docs/narr/declarative.rst') diff --git a/docs/narr/declarative.rst b/docs/narr/declarative.rst index deccb6c48..12deb90e7 100644 --- a/docs/narr/declarative.rst +++ b/docs/narr/declarative.rst @@ -1266,9 +1266,143 @@ which we assume lives in a ``subscribers.py`` module within your application: See also :ref:`subscriber_directive` and :ref:`events_chapter`. +.. index:: + single: not found view + +.. _notfound_zcml: + +Configuring a Not Found View via ZCML +------------------------------------- + +If your application uses :term:`ZCML`, you can replace the Not Found view by +placing something like the following ZCML in your ``configure.zcml`` file. + +.. code-block:: xml + :linenos: + + + +Replace ``helloworld.views.notfound_view`` with the Python dotted name to the +notfound view you want to use. + +See :ref:`changing_the_notfound_view` for more information. + +.. index:: + single: forbidden view + +.. _forbidden_zcml: + +Configuring a Forbidden View via ZCML +------------------------------------- + +If your application uses :term:`ZCML`, you can replace the Forbidden view by +placing something like the following ZCML in your ``configure.zcml`` file. + +.. code-block:: xml + :linenos: + + + +Replace ``helloworld.views.forbidden_view`` with the Python dotted name to +the forbidden view you want to use. + +See :ref:`changing_the_forbidden_view` for more information. + +.. _changing_traverser_zcml: + +Configuring an Alternate Traverser via ZCML +------------------------------------------- + +Use an ``adapter`` stanza in your application's ``configure.zcml`` to +change the default traverser: + +.. code-block:: xml + :linenos: + + + +Or to register a traverser for a specific resource type: -.. Todo -.. ---- +.. code-block:: xml + :linenos: + + + +See :ref:`changing_the_traverser` for more information. + +.. index:: + single: url generator + +.. _changing_resource_url_zcml: + +Changing ``resource_url`` URL Generation via ZCML +------------------------------------------------- + +You can change how :func:`pyramid.url.resource_url` generates a URL for a +specific type of resource by adding an adapter statement to your +``configure.zcml``. + +.. code-block:: xml + :linenos: + + + +See :ref:`changing_resource_url` for more information. + +.. _changing_request_factory_zcml: + +Changing the Request Factory via ZCML +------------------------------------- + +A ``MyRequest`` class can be registered via ZCML as a request factory through +the use of the ZCML ``utility`` directive. In the below, we assume it lives +in a package named ``mypackage.mymodule``. + +.. code-block:: xml + :linenos: + + + +See :ref:`changing_request_factory` for more information. + +.. _adding_renderer_globals_zcml: + +Changing the Renderer Globals Factory via ZCML +---------------------------------------------- + +A renderer globals factory can be registered via ZCML as a through the use of +the ZCML ``utility`` directive. In the below, we assume a +``renderers_globals_factory`` function lives in a package named +``mypackage.mymodule``. + +.. code-block:: xml + :linenos: + + -.. - hooks chapter still has topics for ZCML +See :ref:`adding_renderer_globals` for more information. -- cgit v1.2.3 From d1432f4f3c48106252b292f19442bf591c554fa5 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 27 Dec 2010 00:57:34 -0500 Subject: - Reconcile "extending an existing application" chapter with existence of "advanced configuration" chapter. --- docs/narr/declarative.rst | 66 ++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 54 insertions(+), 12 deletions(-) (limited to 'docs/narr/declarative.rst') diff --git a/docs/narr/declarative.rst b/docs/narr/declarative.rst index 12deb90e7..6654c3dcd 100644 --- a/docs/narr/declarative.rst +++ b/docs/narr/declarative.rst @@ -3,28 +3,27 @@ Declarative Configuration ========================= -The mode of configuration most comprehensively detailed by examples in -narrative chapters in this book is "imperative" configuration. This is the -configuration mode in which a developer cedes the least amount of control to -the framework; it's "imperative" because you express the configuration -directly in Python code, and you have the full power of Python at your -disposal as you issue configuration statements. However, another mode of -configuration exists within :app:`Pyramid`, which often provides better -extensibility and configuration conflict detection. +The mode of configuration detailed in the majority of examples within this +this book is "imperative" configuration. This is the configuration mode in +which a developer cedes the least amount of control to the framework; it's +"imperative" because you express the configuration directly in Python code, +and you have the full power of Python at your disposal as you issue +configuration statements. However, another mode of configuration exists +within :app:`Pyramid` named :term:`ZCML` which often provides better +opportunity for extensibility. A complete listing of ZCML directives is available within :ref:`zcml_directives`. This chapter provides an overview of how you might get started with ZCML and highlights some common tasks performed when you use -ZCML. You can get a better understanding of when it's appropriate to use -ZCML from :ref:`extending_chapter`. +ZCML. .. index:: single: declarative configuration .. _declarative_configuration: -Declarative Configuration -------------------------- +ZCML Configuration +------------------ A :app:`Pyramid` application can be configured "declaratively", if so desired. Declarative configuration relies on *declarations* made external to @@ -163,6 +162,8 @@ configure your application; instead you need to use :term:`ZCML`. .. index:: single: ZCML conflict detection +.. _zcml_conflict_detection: + ZCML Conflict Detection ~~~~~~~~~~~~~~~~~~~~~~~ @@ -345,6 +346,8 @@ contain other directives. See also :ref:`configure_directive` and :ref:`word_on_xml_namespaces`. +.. _the_include_tag: + The ```` Tag ~~~~~~~~~~~~~~~~~~~~~ @@ -478,6 +481,45 @@ declaratively. More information about this mode of configuration is available in :ref:`declarative_configuration` and within :ref:`zcml_reference`. +.. index:: + single: ZCML granularity + +ZCML Granularity +~~~~~~~~~~~~~~~~ + +It's extremely helpful to third party application "extenders" (aka +"integrators") if the :term:`ZCML` that composes the configuration for an +application is broken up into separate files which do very specific things. +These more specific ZCML files can be reintegrated within the application's +main ``configure.zcml`` via ```` +declarations. When ZCML files contain sets of specific declarations, an +integrator can avoid including any ZCML he does not want by including only +ZCML files which contain the declarations he needs. He is not forced to +"accept everything" or "use nothing". + +For example, it's often useful to put all ```` declarations in a +separate ZCML file, as ```` statements have a relative ordering that +is extremely important to the application: if an extender wants to add a +route to the "middle" of the routing table, he will always need to disuse all +the routes and cut and paste the routing configuration into his own +application. It's useful for the extender to be able to disuse just a +*single* ZCML file in this case, accepting the remainder of the configuration +from other :term:`ZCML` files in the original application. + +Granularizing ZCML is not strictly required. An extender can always disuse +*all* your ZCML, choosing instead to copy and paste it into his own package, +if necessary. However, doing so is considerate, and allows for the best +reusability. Sometimes it's possible to include only certain ZCML files from +an application that contain only the registrations you really need, omitting +others. But sometimes it's not. For brute force purposes, when you're +getting ``view`` or ``route`` registrations that you don't actually want in +your overridden application, it's always appropriate to just *not include* +any ZCML file from the overridden application. Instead, just cut and paste +the entire contents of the ``configure.zcml`` (and any ZCML file included by +the overridden application's ``configure.zcml``) into your own package and +omit the ```` ZCML declaration in the overriding +package's ``configure.zcml``. + .. _zcml_scanning: Scanning via ZCML -- cgit v1.2.3 From cfb6c56c2f4ba9fc477de0c461f2b757f6f9d9c1 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 27 Dec 2010 01:01:33 -0500 Subject: remove unnecessary use of begin/end --- docs/narr/declarative.rst | 14 -------------- 1 file changed, 14 deletions(-) (limited to 'docs/narr/declarative.rst') diff --git a/docs/narr/declarative.rst b/docs/narr/declarative.rst index 6654c3dcd..f36e55b29 100644 --- a/docs/narr/declarative.rst +++ b/docs/narr/declarative.rst @@ -47,9 +47,7 @@ In a file named ``helloworld.py``: if __name__ == '__main__': config = Configurator() - config.begin() config.load_zcml('configure.zcml') - config.end() app = config.make_wsgi_app() serve(app, host='0.0.0.0') @@ -82,9 +80,7 @@ the ``if __name__ == '__main__'`` section of ``helloworld.py``: if __name__ == '__main__': config = Configurator() - config.begin() config.add_view(hello_world) - config.end() app = config.make_wsgi_app() serve(app, host='0.0.0.0') @@ -98,9 +94,7 @@ it now reads as: if __name__ == '__main__': config = Configurator() - config.begin() config.load_zcml('configure.zcml') - config.end() app = config.make_wsgi_app() serve(app, host='0.0.0.0') @@ -225,9 +219,7 @@ To do so, first, create a file named ``helloworld.py``: if __name__ == '__main__': config = Configurator() - config.begin() config.load_zcml('configure.zcml') - config.end() app = config.make_wsgi_app() serve(app, host='0.0.0.0') @@ -270,10 +262,8 @@ within the ``if __name__ == '__main__'`` section of ``helloworld.py``: if __name__ == '__main__': config = Configurator() - config.begin() config.add_view(hello_world) config.add_view(goodbye_world, name='goodbye') - config.end() app = config.make_wsgi_app() serve(app, host='0.0.0.0') @@ -288,9 +278,7 @@ name='goodbye')``, so that it now reads as: if __name__ == '__main__': config = Configurator() - config.begin() config.load_zcml('configure.zcml') - config.end() app = config.make_wsgi_app() serve(app, host='0.0.0.0') @@ -545,9 +533,7 @@ file points to is scanned. if __name__ == '__main__': from pyramid.config import Configurator config = Configurator() - config.begin() config.load_zcml('configure.zcml') - config.end() app = config.make_wsgi_app() serve(app, host='0.0.0.0') -- cgit v1.2.3