diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/narr/handlers.rst | 27 |
1 files changed, 19 insertions, 8 deletions
diff --git a/docs/narr/handlers.rst b/docs/narr/handlers.rst index f9b073dae..dcb199bbc 100644 --- a/docs/narr/handlers.rst +++ b/docs/narr/handlers.rst @@ -28,7 +28,7 @@ handler configuration. The :meth:`pyramid.configuration.Configurator.add_handler` method will scan the handler class and automatically set up views for methods that are -auto-exposed or have an ``__exposed__`` attribute. The +auto-exposed or were decorated with :class:`~pyramid.view.action`. The :class:`~pyramid.view.action` decorator is used to setup additional view configuration information for individual class methods, and can be used repeatedly for a single method to register multiple view configurations that @@ -89,9 +89,22 @@ Using :meth:`~pyramid.configuration.Configurator.add_handler` When calling :meth:`~pyramid.configuration.Configurator.add_handler`, an ``action`` is required in either the route pattern or as a keyword argument, -but **cannot appear in both places**. Additional keyword arguments are passed +but **cannot appear in both places**. A ``handler`` argument must also be +supplied, which can be either a :term:`resource specification` or a Python +reference to the handler class. Additional keyword arguments are passed directly through to :meth:`pyramid.configuration.Configurator.add_route`. +For example: + +.. code-block:: python + + config.add_handler('hello', '/hello/:action', + handler='mypackage.handlers:MyHandler') + +In larger applications, it is advised to use a :term:`resource specification` +with :meth:`~pyramid.configuration.Configurator.add_handler` to avoid having +to import every handler class. + Multiple :meth:`~pyramid.configuration.Configurator.add_handler` calls can specify the same handler, to register specific route names for different handler/action combinations. For example: @@ -115,9 +128,7 @@ view configurations being registered. When :meth:`~pyramid.configuration.Configurator.add_handler` runs, every method in the handler class will be searched and a view registered if the method name matches the ``__autoexpose__`` regular expression, or if the -method has a ``__exposed__`` attribute. The ``__exposed__`` attribute for a -function should never be set manually, the :class:`~pyramid.view.action` -decorator will configure it. +method was decorated with :class:`~pyramid.view.action`. Auto-exposed Views ------------------ @@ -152,13 +163,13 @@ Action Decorator ---------------- The :class:`~pyramid.view.action` decorator registers view configuration -information on the method's ``__exposed__`` attribute, which is used by +information on the handler method which is used by :meth:`~pyramid.configuration.Configurator.add_handler` to setup the view configuration. All keyword arguments are recorded, and passed to -:meth:`pyramid.configuration.Configurator.add_view`. Any valid keyword -arguments for :meth:`pyramid.configuration.Configurator.add_view` can thus be +:meth:`!pyramid.configuration.Configurator.add_view`. Any valid keyword +arguments for :meth:`!pyramid.configuration.Configurator.add_view` can thus be used with the :class:`~pyramid.view.action` decorator to further restrict when the view will be called. |