From e8edd5ff7157c9a11b6478702c1e45bb46f11344 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 9 Dec 2010 04:04:39 -0500 Subject: - Add a ``handler`` ZCML directive. This directive does the same thing as ``pyramid.configuration.add_handler``. --- docs/narr/declarative.rst | 51 +++++++++++++++++++++++++++++++++++++++++------ docs/narr/handlers.rst | 6 ++++++ 2 files changed, 51 insertions(+), 6 deletions(-) (limited to 'docs/narr') diff --git a/docs/narr/declarative.rst b/docs/narr/declarative.rst index 31d6fc575..99c5a75ac 100644 --- a/docs/narr/declarative.rst +++ b/docs/narr/declarative.rst @@ -644,12 +644,11 @@ See :ref:`view_directive` for complete ZCML directive documentation. Configuring a Route via ZCML ---------------------------- -Instead of using the imperative -:meth:`pyramid.config.Configurator.add_route` method to add a new -route, you can alternately use :term:`ZCML`. :ref:`route_directive` -statements in a :term:`ZCML` file used by your application is a sign that -you're using :term:`URL dispatch`. For example, the following :term:`ZCML -declaration` causes a route to be added to the application. +Instead of using the imperative :meth:`pyramid.config.Configurator.add_route` +method to add a new route, you can alternately use :term:`ZCML`. +:ref:`route_directive` statements in a :term:`ZCML` file. For example, the +following :term:`ZCML declaration` causes a route to be added to the +application. .. code-block:: xml :linenos: @@ -679,6 +678,46 @@ is the order that they appear relative to each other in the ZCML file. See :ref:`route_directive` for full ``route`` ZCML directive documentation. +.. _zcml_handler_configuration: + +Configuring a Handler via ZCML +------------------------------ + +Instead of using the imperative +:meth:`pyramid.config.Configurator.add_handler` method to add a new +route, you can alternately use :term:`ZCML`. :ref:`handler_directive` +statements in a :term:`ZCML` file used by your application is a sign that +you're using :term:`URL dispatch`. For example, the following :term:`ZCML +declaration` causes a route to be added to the application. + +.. code-block:: xml + :linenos: + + + +.. note:: + + Values prefixed with a period (``.``) within the values of ZCML attributes + such as the ``handler`` attribute of a ``handler`` directive mean + "relative to the Python package directory in which this :term:`ZCML` file + is stored". So if the above ``handler`` declaration was made inside a + ``configure.zcml`` file that lived in the ``hello`` package, you could + replace the relative ``.views.MyHandler`` with the absolute + ``hello.views.MyHandler`` Either the relative or absolute form is + functionally equivalent. It's often useful to use the relative form, in + case your package's name changes. It's also shorter to type. + +The order that the routes attached to handlers are evaluated when declarative +configuration is used is the order that they appear relative to each other in +the ZCML file. + +See :ref:`handler_directive` for full ``handler`` ZCML directive +documentation. + .. index:: triple: view; zcml; static resource diff --git a/docs/narr/handlers.rst b/docs/narr/handlers.rst index 49dd73f7f..9a5267b2a 100644 --- a/docs/narr/handlers.rst +++ b/docs/narr/handlers.rst @@ -86,6 +86,12 @@ This will result one of the methods that are configured for the ``action`` of handler class not named 'index' might be called if they were configured to be called when the ``action`` name is 'index' as will be seen below. +.. note:: + + Handler configuration may also be added to the system via :term:`ZCML` (see + :ref:`zcml_handler_configuration`). + +.. _using_add_handler: Using :meth:`~pyramid.config.Configurator.add_handler` ------------------------------------------------------------- -- cgit v1.2.3