From e77864c970e37e77b246eeb8e8426c3bc74f52f8 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 17 Jan 2010 18:47:31 +0000 Subject: Checklist. --- docs/narr/urldispatch.rst | 239 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 239 insertions(+) (limited to 'docs') diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index 8a7b86f2d..84a02f114 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -344,6 +344,18 @@ each other. For routes added via the order that routes are evaluated is the order in which they are added to the configuration imperatively. +For example, route configuration statements with the following +patterns might be added in the following order: + +.. code-block:: text + + members/:def + members/abc + +In such a configuration, the ``members/abc`` pattern would *never* be +matched; this is because the match ordering will always match +``members/:def`` first and ``members/abc`` will never be reached. + .. index:: pair: route; factory @@ -379,6 +391,222 @@ can maintain a separate :term:`ACL`, as in wish to combine URL dispatch with :term:`traversal` as documented within :ref:`hybrid_chapter`. +Route Configuration Arguments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Route configuration statements may specify a large number of +arguments. + +Many of these arguments are :term:`route predicate` arguments. A +route predicate argument specifies that some aspect of the request +must be true for the associated route to be considered a match during +the route matching process. + +Other arguments are view configuration related arguments. These only +have an effect when the route configuration names a ``view``. + +Other arguments are ``name`` and ``factory``. These are required +arguments but represent neither a predicate nor view configuration +information. + +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 ++++++++++++++++++++ + +``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 + route to match. This is useful for detecting AJAX requests issued + from jQuery, Prototype and other Javascript libraries. If this + 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 + ``POST`` variable) that has a name which matches the supplied value. + If the value supplied as the argument has a ``=`` sign in it, + e.g. ``request_params="foo=123"``, then the key (``foo``) must both + exist in the ``request.params`` dictionary, and the value must match + the right hand side of the expression (``123``) for the route to + "match" the current request. If this predicate returns ``False``, + 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 + ``Host:localhost``). If the value contains a colon, the value + portion should be a regular expression. If the value does not + contain a colon, the entire value will be considered to be the + header name (e.g. ``If-Modified-Since``). If the value evaluates to + a header name only without a value, the header specified by the name + must be present in the request for this predicate to be true. If + the value evaluates to a header name/value pair, the header + specified by the name must be present in the request *and* the + regular expression specified as the value must match the header + value. Whether or not the value represents a header name or a + header name/value pair, the case of the header name is not + significant. If this predicate returns ``False``, route matching + 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 + ``text/plain``, a wildcard mimetype match token in the form + ``text/*`` or a match-all wildcard mimetype match token in the form + ``*/*``. If any of the forms matches the ``Accept`` header of the + request, this predicate will be true. If this predicate returns + ``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 + with predefined predicates as necessary. Each custom predicate + callable should accept two arguments: ``context`` and ``request`` + and should return either ``True`` or ``False`` after doing arbitrary + evaluation of the context and/or the request. If all callables + return ``True``, the associated route will be considered viable for + a given request. If any custom predicate returns ``False``, route + matching continues. Note that the value ``context`` will always be + ``None`` when passed to a custom route predicate. + +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`` + attribute is used. If this attribute is not specified, the default + (``None``) will be used. + + If the ``view`` argument is not provided, this argument has + no effect. + + 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). + + If the ``view`` attribute is not provided, this argument has + no effect. + + 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 + term (does not contain a dot ``.``), the specified term will be used + to look up a renderer implementation, and that renderer + implementation will be used to construct a response from the view + return value. If the renderer term contains a dot (``.``), the + specified term will be treated as a path, and the filename extension + of the last element in the path will be used to look up the renderer + implementation, which will be passed the full path. The renderer + implementation will be used to construct a response from the view + return value. See :ref:`views_which_use_a_renderer` for more + information. + + If the ``view`` argument is not provided, this argument has + no effect. + + 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. + + If the ``view`` argument is not provided, this argument has + no effect. + + 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 + called. Your models must be 'location-aware' to use this feature. + See :ref:`location_aware` for more information about + location-awareness. + + If the ``view`` argument is not provided, this argument has no + 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 + allows you to vary the method attribute used to obtain the response. + For example, if your view was a class, and the class has a method + named ``index`` and you wanted to use this method instead of the + class' ``__call__`` method to return the response, you'd say + ``attr="index"`` in the view configuration for the view. This is + most useful when the view definition is a class. + + If the ``view`` argument is not provided, this argument has no + effect. + Route Matching -------------- @@ -400,10 +628,21 @@ otherwise known as :term:`context finding`. During view lookup, if any ``view`` argument was provided within the matched route configuration, the :term:`view callable` it points to is called. +When a route configuration is declared, it may contain :term:`route +predicate` arguments. All route predicates associated with a route +declaration must be ``True`` for the route configuration to be used +for a given request. + +If any predicate in the set of :term:`route predicate` arguments +provided to a route configuration returns ``False``, that route is +skipped and route matching continues through the ordered set of +routes. + If no route matches after all route patterns are exhausted, :mod:`repoze.bfg` falls back to :term:`traversal` to do :term:`context finding` and :term:`view lookup`. + .. index:: pair: URL dispatch; matchdict -- cgit v1.2.3