diff options
Diffstat (limited to 'docs/zcml/route.rst')
| -rw-r--r-- | docs/zcml/route.rst | 223 |
1 files changed, 0 insertions, 223 deletions
diff --git a/docs/zcml/route.rst b/docs/zcml/route.rst deleted file mode 100644 index 0f94fa11b..000000000 --- a/docs/zcml/route.rst +++ /dev/null @@ -1,223 +0,0 @@ -.. _route_directive: - -``route`` ---------- - -The ``route`` directive adds a single :term:`route configuration` to -the :term:`application registry`. - -Attributes -~~~~~~~~~~ - -``pattern`` - The pattern of the route e.g. ``ideas/{idea}``. This attribute is - required. See :ref:`route_pattern_syntax` for information - about the syntax of route patterns. - - .. note:: For backwards compatibility purposes, the ``path`` - attribute can also be used instead of ``pattern``. - -``name`` - The name of the route, e.g. ``myroute``. This attribute is - required. It must be unique among all defined routes in a given - configuration. - -``factory`` - The :term:`dotted Python name` to a function that will generate a - :app:`Pyramid` context object when this route matches. - e.g. ``mypackage.resources.MyResource``. If this argument is not - specified, a default root factory will be used. - -``view`` - The :term:`dotted Python name` to a function that will be used as a - view callable when this route matches. - e.g. ``mypackage.views.my_view``. - -``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. - -``traverse`` - If you would like to cause the :term:`context` to be something other - than the :term:`root` object when this route matches, you can spell - a traversal pattern as the ``traverse`` argument. This traversal - pattern will be used as the traversal path: traversal will begin at - the root object implied by this route (either the global root, or - the object returned by the ``factory`` associated with this route). - - The syntax of the ``traverse`` argument is the same as it is for - ``pattern``. For example, if the ``pattern`` provided to the - ``route`` directive is ``articles/{article}/edit``, and the - ``traverse`` argument provided to the ``route`` directive is - ``/{article}``, when a request comes in that causes the route to - match in such a way that the ``article`` match value is '1' (when - the request URI is ``/articles/1/edit``), the traversal path will be - generated as ``/1``. This means that the root object's - ``__getitem__`` will be called with the name ``1`` during the - traversal phase. If the ``1`` object exists, it will become the - :term:`context` of the request. :ref:`traversal_chapter` has more - information about traversal. - - If the traversal path contains segment marker names which are not - present in the ``pattern`` argument, a runtime error will occur. - The ``traverse`` pattern should not contain segment markers that do - not exist in the ``pattern``. - - A similar combining of routing and traversal is available when a - route is matched which contains a ``*traverse`` remainder marker in - its ``pattern`` (see :ref:`using_traverse_in_a_route_pattern`). The - ``traverse`` argument to the ``route`` directive allows you to - associate route patterns with an arbitrary traversal path without - using a a ``*traverse`` remainder marker; instead you can use other - match information. - - Note that the ``traverse`` argument to the ``route`` directive is - ignored when attached to a route that has a ``*traverse`` remainder - marker in its pattern. - -``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`` - The value of this attribute represents a regular expression pattern - that will be tested against the ``PATH_INFO`` WSGI environment - variable. If the regex matches, this predicate will be true. If - this predicate returns false, route matching continues. - -``request_param`` - This value can be any string. A view declaration with this - attribute 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 to the attribute 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`` - The value of this attribute represents an HTTP header name or a - header name/value pair. If the value contains a ``:`` (colon), it - will be considered a name/value pair (e.g. ``User-Agent:Mozilla/.*`` - or ``Host:localhost``). The *value* of an attribute that represent - a name/value pair 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`` - The value of this attribute 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: ``info`` and ``request`` - and should return either ``True`` or ``False`` after doing arbitrary - evaluation of the info and/or the request. If all custom and - non-custom predicate callables return ``True`` the associated route - will be considered viable for a given request. If any predicate - callable returns ``False``, route matching continues. Note that the - value ``info`` passed to a custom route predicate is a dictionary - containing matching information; see :ref:`custom_route_predicates` - for more information about ``info``. - -``view_context`` - The :term:`dotted Python name` to a class or an interface that the - :term:`context` of the view should match for the view named by the - route to be used. This attribute is only useful if the ``view`` - attribute is used. If this attribute is not specified, the default - (``None``) will be used. - - If the ``view`` attribute is not provided, this attribute has no - effect. - - This attribute can also be spelled as ``view_for`` or ``for_``; - these are valid older spellings. - -``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 attribute has no - effect. - - This attribute 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:`asset 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`` attribute is not provided, this attribute has no - effect. - - This attribute can also be spelled as ``renderer``. - -``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`` attribute is not provided, this attribute has no - effect. - -``use_global_views`` - When a request matches this route, and view lookup cannot find a view - which has a 'route_name' predicate argument that matches the route, - try to fall back to using a view that otherwise matches the context, - request, and view name (but does not match the route name predicate). - -Alternatives -~~~~~~~~~~~~ - -You can also add a :term:`route configuration` via: - -- Using the :meth:`pyramid.config.Configurator.add_route` method. - -See Also -~~~~~~~~ - -See also :ref:`urldispatch_chapter`. |