- Small url dispatch overhaul: the ``connect`` method of the

    ``urldispatch.RoutesMapper`` object now accepts a keyword
    parameter named ``context_factory``.  If this parameter is
    supplied, it must be a callable which returns an instance.  This
    instance is used as the context for the request when a route is
    matched.

  - The registration of a RoutesModelTraverser no longer needs to be
    performed by the application; it's in the bfg ZCML now.

1 files changed, 38 insertions, 29 deletions

diff --git a/docs/api/urldispatch.rst b/docs/api/urldispatch.rst
index 8d4930d34..40b22e5bc 100644
--- a/docs/api/urldispatch.rst
+++ b/docs/api/urldispatch.rst
@@ -8,42 +8,51 @@
   .. autoclass:: RoutesMapper
      :members:
 
-You can configure the ``RoutesModelTraverser`` into your application's
-configure.zcml like so::
+An example of configuring a ``bfg:view`` stanza in ``configure.zcml``
+that maps a context found via :term:`Routes` URL dispatch to a view
+function is as follows:
 
-  <adapter
-      factory="repoze.bfg.urldispatch.RoutesModelTraverser"
-      provides="repoze.bfg.interfaces.ITraverserFactory"
-      for="repoze.bfg.interfaces.IURLDispatchModel
-           repoze.bfg.interfaces.IRequest"
-  />
+.. code-block:: xml
+   :linenos:
 
-An example of configuring a view that is willing to handle this sort
-of dispatch::
+   <bfg:view
+       for="repoze.bfg.interfaces.IRoutesContext"
+       view=".views.articles_view"
+       name="articles"
+       />
 
-  <bfg:view
-      for="repoze.bfg.interfaces.IURLDispatchModel"
-      view=".views.articles_view"
-      name="articles"
-      />
+All context objects found via Routes URL dispatch will provide the
+``IRoutesContext`` interface (attached dynamically).  You might then
+configure the ``RoutesMapper`` like so:
 
-You might then configure the ``RoutesMapper`` like so::
+.. code-block:: python
+   :linenos:
 
-  def fallback_get_root(environ):
-      return {} # the graph traversal root is empty in this example
+   def fallback_get_root(environ):
+       return {} # the graph traversal root is empty in this example
 
-  get_root = RoutesMapper(fallback_get_root)
-  get_root.connect('archives/:article', controller='articles')
+   class Article(object):
+       def __init__(self, **kw):
+           self.__dict__update(kw)
 
-  import myapp
-  from repoze.bfg.router import make_app
+   get_root = RoutesMapper(fallback_get_root)
+   get_root.connect('archives/:article', controller='articles',
+                    context_factory=Article)
 
-  app = make_app(get_root, myapp)
+   import myapp
+   from repoze.bfg.router import make_app
+
+   app = make_app(get_root, myapp)
+
+The effect of this configuration: when this :mod:`repoze.bfg`
+application runs, if any URL matches the pattern
+``archives/:article``, the ``.views.articles_view`` view will be
+called with its :term:`context` as a instance of the ``Article``
+class.  The ``Article`` instance will have attributes matching the
+keys and values in the Routes routing dictionary associated with the
+request.
 
-At this point, if any URL matches the pattern ``archives/:article``,
-the ``.views.articles_view`` view will be called with its context as a
-only-the-fly-generated-model with attributes matching the keys and
-values in the Routes routing dictionary associated with the request.
 In this case in particular, when a user visits
-``/archives/something``, the model will have an ``article`` attribute
-with the value of ``something``.
+``/archives/something``, the context will be an instance of the
+Article class and it will have an ``article`` attribute with the value
+of ``something``.