- Add a ``handler`` ZCML directive. This directive does the same thing as

  ``pyramid.configuration.add_handler``.

2 files changed, 51 insertions, 6 deletions

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:
+
+   <handler
+     route_name="myroute"
+     pattern="/prefix/{action}"
+     handler=".handlers.MyHandler"
+    />
+
+.. 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`
 -------------------------------------------------------------