From 39fccbbfbceacaf1b3d5fb6f03a07fbe4d861969 Mon Sep 17 00:00:00 2001
From: Chris McDonough <chrism@agendaless.com>
Date: Wed, 6 Aug 2008 03:30:40 +0000
Subject:   - 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.
---
 docs/api/urldispatch.rst | 67 +++++++++++++++++++++++++++---------------------
 1 file changed, 38 insertions(+), 29 deletions(-)

(limited to 'docs')

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``.
-- 
cgit v1.2.3