From 74409d12f7eb085bc992a200cc74799e4d1ff355 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 8 Sep 2010 04:25:35 +0000 Subject: - The ``repoze.bfg.urldispatch.Route`` constructor (not an API) now accepts a different ordering of arguments. Previously it was ``(pattern, name, factory=None, predicates=())``. It is now ``(name, pattern, factory=None, predicates=())``. This is in support of consistency with ``configurator.add_route``. - The ``repoze.bfg.urldispatch.RoutesMapper.connect`` method (not an API) now accepts a different ordering of arguments. Previously it was ``(pattern, name, factory=None, predicates=())``. It is now ``(name, pattern, factory=None, predicates=())``. This is in support of consistency with ``configurator.add_route``. - The ``repoze.bfg.urldispatch.RoutesMapper`` object now has a ``get_route`` method which returns a single Route object or ``None``. - A new interface ``repoze.bfg.interfaces.IRoute`` was added. The ``repoze.bfg.urldispatch.Route`` object implements this interface. - The canonical attribute for accessing the routing pattern from a route object is now ``pattern`` rather than ``path``. - The argument to ``repoze.bfg.configuration.Configurator.add_route`` which was previously called ``path`` is now called ``pattern`` for better explicability. For backwards compatibility purposes, passing a keyword argument named ``path`` to ``add_route`` will still work indefinitely. - The ``path`` attribute to the ZCML ``route`` directive is now named ``pattern`` for better explicability. The older ``path`` attribute will continue to work indefinitely. - All narrative, API, and tutorial docs which referred to a route pattern as a ``path`` have now been updated to refer to them as a ``pattern``. - The routesalchemy template has been updated to use ``pattern`` in its route declarations rather than ``path``. --- docs/zcml/route.rst | 43 ++++++++++++++++++++++++------------------- 1 file changed, 24 insertions(+), 19 deletions(-) (limited to 'docs/zcml') diff --git a/docs/zcml/route.rst b/docs/zcml/route.rst index b4a318043..4290ea3ae 100644 --- a/docs/zcml/route.rst +++ b/docs/zcml/route.rst @@ -9,10 +9,14 @@ the :term:`application registry`. Attributes ~~~~~~~~~~ -``path`` - The path of the route e.g. ``ideas/:idea``. This attribute is - required. See :ref:`route_path_pattern_syntax` for information - about the syntax of route paths. +``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``. ``pattern`` + is the preferred spelling as of :mod:`repoze.bfg` 1.3. ``name`` The name of the route, e.g. ``myroute``. This attribute is @@ -49,25 +53,26 @@ Attributes the object returned by the ``factory`` associated with this route). The syntax of the ``traverse`` argument is the same as it is for - ``path``. For example, if the ``path`` 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. + ``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 path argument, a runtime error will occur. The - ``traverse`` pattern should not contain segment markers that do not - exist in the ``path``. + 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 path (see :ref:`using_traverse_in_a_route_path`). The + 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 @@ -75,7 +80,7 @@ Attributes Note that the ``traverse`` argument to the ``route`` directive is ignored when attached to a route that has a ``*traverse`` remainder - marker in its path. + marker in its pattern. .. note:: This feature is new as of :mod:`repoze.bfg` 1.3. -- cgit v1.2.3