diff options
| -rw-r--r-- | docs/narr/firstapp.rst | 4 | ||||
| -rw-r--r-- | docs/narr/urldispatch.rst | 28 | ||||
| -rw-r--r-- | docs/narr/views.rst | 52 |
3 files changed, 6 insertions, 78 deletions
diff --git a/docs/narr/firstapp.rst b/docs/narr/firstapp.rst index 9bbe0d70a..158cb2a56 100644 --- a/docs/narr/firstapp.rst +++ b/docs/narr/firstapp.rst @@ -636,14 +636,14 @@ completely equivalent: We've now configured a :mod:`repoze.bfg` helloworld application declaratively. More information about this mode of configuration is available in :ref:`declarative_configuration` and within -:ref:`zcml_directives`. +:ref:`zcml_reference`. References ---------- For more information about the API of a :term:`Configurator` object, see :class:`repoze.bfg.configuration.Configurator` . The equivalent -ZCML declaration tags are introduced in :ref:`zcml_directives`. +ZCML declaration tags are introduced in :ref:`zcml_reference`. For more information about :term:`view configuration`, see :ref:`views_chapter`. diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 84a02f114..25149f30f 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -171,7 +171,7 @@ we'll explain how it *does* work in the following section. You can skip it if you're uninterested. Route View Callable Registration and Lookup Details -+++++++++++++++++++++++++++++++++++++++++++++++++++ +!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! When a ``view`` attribute is attached to a route configuration, :mod:`repoze.bfg` ensures that a :term:`view configuration` is @@ -409,35 +409,29 @@ Other arguments are ``name`` and ``factory``. These are required arguments but represent neither a predicate nor view configuration information. -Non-Predicate Arguments -+++++++++++++++++++++++ +**Non-Predicate Arguments** ``name`` - The name of the route, e.g. ``myroute``. This attribute is required. It must be unique among all defined routes in a given application. ``factory`` - A reference to a Python object (often a function or a class) that will generate a :mod:`repoze.bfg` :term:`context` object when this route matches. For example, ``mypackage.models.MyFactoryClass``. If this argument is not specified, the traversal root factory will be used. -Predicate Arguments -+++++++++++++++++++ +**Predicate Arguments** ``path`` - The path of the route e.g. ``ideas/:idea``. This argument is required. See :ref:`route_path_pattern_syntax` for information about the syntax of route paths. If the path doesn't match the current URL, route matching continues. ``xhr`` - This value should be either ``True`` or ``False``. If this value is specified and is ``True``, the :term:`request` must possess an ``HTTP_X_REQUESTED_WITH`` (aka ``X-Requested-With``) header for this @@ -446,21 +440,18 @@ Predicate Arguments predicate returns ``False``, route matching continues. ``request_method`` - A string representing an HTTP method name, e.g. ``GET``, ``POST``, ``HEAD``, ``DELETE``, ``PUT``. If this argument is not specified, this route will match if the request has *any* request method. If this predicate returns ``False``, route matching continues. ``path_info`` - This value represents a regular expression pattern that will be tested against the ``PATH_INFO`` WSGI environment variable. If the regex matches, this predicate will return ``True``. If this predicate returns ``False``, route matching continues. ``request_param`` - This value can be any string. A view declaration with this argument ensures that the associated route will only match when the request has a key in the ``request.params`` dictionary (an HTTP ``GET`` or @@ -473,7 +464,6 @@ Predicate Arguments route matching continues. ``header`` - This argument represents an HTTP header name or a header name/value pair. If the argument contains a ``:`` (colon), it will be considered a name/value pair (e.g. ``User-Agent:Mozilla/.*`` or @@ -492,7 +482,6 @@ Predicate Arguments continues. ``accept`` - This value represents a match query for one or more mimetypes in the ``Accept`` HTTP request header. If this value is specified, it must be in one of the following forms: a mimetype match token in the form @@ -503,7 +492,6 @@ Predicate Arguments ``False``, route matching continues. ``custom_predicates`` - This value should be a sequence of references to custom predicate callables. Use custom predicates when no set of predefined predicates does what you need. Custom predicates can be combined @@ -516,16 +504,13 @@ Predicate Arguments matching continues. Note that the value ``context`` will always be ``None`` when passed to a custom route predicate. -View-Related Arguments -++++++++++++++++++++++ +**View-Related Arguments** ``view`` - A reference to a Python object that will be used as a view callable when this route matches. e.g. ``mypackage.views.my_view``. ``view_context`` - A reference to a class or an :term:`interface` that the :term:`context` of the view should match for the view named by the route to be used. This argument is only useful if the ``view`` @@ -538,7 +523,6 @@ View-Related Arguments This attribute can also be spelled as ``for_`` or ``view_for``. ``view_permission`` - The permission name required to invoke the view associated with this route. e.g. ``edit``. (see :ref:`using_security_with_urldispatch` for more information about permissions). @@ -549,7 +533,6 @@ View-Related Arguments This argument can also be spelled as ``permission``. ``view_renderer`` - This is either a single string term (e.g. ``json``) or a string implying a path or :term:`resource specification` (e.g. ``templates/views.pt``). If the renderer value is a single @@ -570,7 +553,6 @@ View-Related Arguments This argument can also be spelled as ``renderer``. ``view_request_type`` - A reference to an :term:`interface` representing a :term:`request type`. If this argument is not specified, any request type will be considered a match for the view associated with this route. @@ -581,7 +563,6 @@ View-Related Arguments This argument can also be spelled as ``request_type``. ``view_containment`` - This value should be a reference to a Python class or :term:`interface` that a parent object in the :term:`lineage` must provide in order for the view related to this route to be found and @@ -593,7 +574,6 @@ View-Related Arguments effect. ``view_attr`` - The view machinery defaults to using the ``__call__`` method of the view callable (or the function itself, if the view callable is a function) to obtain a response dictionary. The ``attr`` value diff --git a/docs/narr/views.rst b/docs/narr/views.rst index 9af12dd4e..28b8b4290 100644 --- a/docs/narr/views.rst +++ b/docs/narr/views.rst @@ -531,27 +531,22 @@ values on the ``request`` object via ``setattr`` within the view callable to influence associated response attributes. ``response_content_type`` - Defines the content-type of the resulting response, e.g. ``text/xml``. ``response_headerlist`` - A sequence of tuples describing cookie values that should be set in the response, e.g. ``[('Set-Cookie', 'abc=123'), ('X-My-Header', 'foo')]``. ``response_status`` - A WSGI-style status code (e.g. ``200 OK``) describing the status of the response. ``response_charset`` - The character set (e.g. ``UTF-8``) of the response. ``response_cache_for`` - A value in seconds which will influence ``Cache-Control`` and ``Expires`` headers in the returned response. The same can also be achieved by returning various values in the ``response_headerlist``, @@ -969,8 +964,6 @@ rendered in a request that has a ``;charset=utf-8`` stanza on its to Unicode objects implicitly in :mod:`repoze.bfg`'s default configuration. The keys are still strings. - - .. index:: single: view configuration pair: view; configuration @@ -1042,7 +1035,6 @@ Non-Predicate Arguments +++++++++++++++++++++++ ``permission`` - The name of a :term:`permission` that the user must possess in order to invoke the :term:`view callable`. See :ref:`view_security_section` for more information about view @@ -1052,7 +1044,6 @@ Non-Predicate Arguments this view (it's accessible by any caller). ``attr`` - The view machinery defaults to using the ``__call__`` method of the :term:`view callable` (or the function itself, if the view callable is a function) to obtain a response. The ``attr`` value allows you @@ -1068,7 +1059,6 @@ Non-Predicate Arguments attribute if the view is a class). ``renderer`` - This is either a single string term (e.g. ``json``) or a string implying a path or :term:`resource specification` (e.g. ``templates/views.pt``) naming a :term:`renderer` @@ -1101,7 +1091,6 @@ Non-Predicate Arguments implementation is never called. ``wrapper`` - The :term:`view name` of a different :term:`view configuration` which will receive the response body of this view as the ``request.wrapped_body`` attribute of its own :term:`request`, and @@ -1123,7 +1112,6 @@ Predicate Arguments +++++++++++++++++++ ``name`` - The :term:`view name` required to match this view callable. Read :ref:`traversal_chapter` to understand the concept of a view name. @@ -1131,7 +1119,6 @@ Predicate Arguments default view). ``context`` - An object representing Python class that the :term:`context` must be an instance of, *or* the :term:`interface` that the :term:`context` must provide in order for this view to be found and called. This @@ -1143,7 +1130,6 @@ Predicate Arguments any model, is used. ``route_name`` - If ``route_name`` is supplied, the view callable will be invoked only when the named route has matched. @@ -1160,7 +1146,6 @@ Predicate Arguments request object that does not indicate it matched a route. ``request_type`` - This value should be an :term:`interface` that the :term:`request` must provide in order for this view to be found and called. @@ -1170,7 +1155,6 @@ Predicate Arguments *This is an advanced feature, not often used by "civilians"*. ``request_method`` - This value can either be one of the strings ``GET``, ``POST``, ``PUT``, ``DELETE``, or ``HEAD`` representing an HTTP ``REQUEST_METHOD``. A view declaration with this argument ensures @@ -1183,7 +1167,6 @@ Predicate Arguments environment. ``request_param`` - This value can be any string. A view declaration with this argument ensures that the view will only be called when the :term:`request` has a key in the ``request.params`` dictionary (an HTTP ``GET`` or @@ -1200,7 +1183,6 @@ Predicate Arguments dictionary. ``containment`` - This value should be a reference to a Python class or term:`interface` that a parent object in the :term:`lineage` must provide in order for this view to be found and called. The nodes in @@ -1214,7 +1196,6 @@ Predicate Arguments location-awareness. ``xhr`` - This value should be either ``True`` or ``False``. If this value is specified and is ``True``, the :term:`WSGI` environment must possess an ``HTTP_X_REQUESTED_WITH`` (aka ``X-Requested-With``) header that @@ -1227,7 +1208,6 @@ Predicate Arguments to invoke the associated view callable. ``accept`` - The value of this argument represents a match query for one or more mimetypes in the ``Accept`` HTTP request header. If this value is specified, it must be in one of the following forms: a mimetype @@ -1241,7 +1221,6 @@ Predicate Arguments the associated view callable. ``header`` - This value represents an HTTP header name or a header name/value pair. @@ -1268,7 +1247,6 @@ Predicate Arguments whether or not to invoke the associated view callable. ``path_info`` - This value represents a regular expression pattern that will be tested against the ``PATH_INFO`` WSGI environment variable to decide whether or not to call the associated view callable. If the regex @@ -1279,7 +1257,6 @@ Predicate Arguments associated view callable. ``custom_predicates`` - If ``custom_predicates`` is specified, it must be a sequence of references to custom predicate callables. Use custom predicates when no set of predefined predicates do what you need. Custom @@ -1839,35 +1816,6 @@ the user's browser, representing a "not found" (404) page. See :ref:`changing_the_notfound_view` for more information about changing the default notfound view. -There are a several exceptions to the the rule which says that view -configuration attributes represent "narrowings". Several attributes -of the ``view`` directive are *not* narrowing predicates. These are -``permission``, ``name``, ``renderer``, and ``attr``. - -The value of the ``permission`` attribute represents the permission -that must be possessed by the user to invoke any found view. When a -view is found that matches all predicates, but the invoking user does -not possess the permission implied by any associated ``permission`` in -the current context, processing stops, and an -:exc:`repoze.bfg.exception.Forbidden` error is raised, usually -resulting in the :term:`forbidden view` being shown to the invoking -user. No further view narrowing or view lookup is done. - -.. note:: - - See :ref:`changing_the_forbidden_view` for more information about - changing the default forbidden view. - -The value of the ``name`` attribute represents a direct match of the -view name returned via traversal. It is part of initial view lookup -rather than a predicate/narrower. - -The value of the ``renderer`` attribute represents the renderer used -to convert non-response return values from a view. - -The value of the ``attr`` attribute represents the attribute name -looked up on the view object to return a response. - .. index:: pair: debugging; not found errors |