Move to renderers.

5 files changed, 75 insertions, 34 deletions

diff --git a/docs/tutorials/bfgwiki/background.rst b/docs/tutorials/bfgwiki/background.rst
index 0e57ef81e..dde516baf 100644
--- a/docs/tutorials/bfgwiki/background.rst
+++ b/docs/tutorials/bfgwiki/background.rst
@@ -12,6 +12,6 @@ To code along with this tutorial, the developer will need a UNIX
 machine with development tools (Mac OS X with XCode, any Linux or BSD
 variant, etc) *or* he will need a Windows system of any kind.
 
-This tutorial is known to work under :mod:`repoze.bfg` version 1.0b1.
+This tutorial is known to work under :mod:`repoze.bfg` version 1.1a5.
 
 Have fun!
diff --git a/docs/tutorials/bfgwiki2/authorization.rst b/docs/tutorials/bfgwiki2/authorization.rst
index d48236d0a..e158b3e87 100644
--- a/docs/tutorials/bfgwiki2/authorization.rst
+++ b/docs/tutorials/bfgwiki2/authorization.rst
@@ -143,18 +143,16 @@ into its template.  We'll add something like this to each view body:
 
    logged_in = authenticated_userid(request)
 
-We'll then change the return value of ``render_template_to_response``
-to pass the `resulting `logged_in`` value to the template, e.g.:
+We'll then change the return value of these views to pass the
+`resulting `logged_in`` value to the template, e.g.:
 
 .. code-block:: python
    :linenos:
 
-   return render_template_to_response('templates/view.pt',
-                                      request = request,
-                                      page = page,
-                                      content = content,
-                                      logged_in = logged_in,
-                                      edit_url = edit_url)
+   return dict(page = page,
+               content = content,
+               logged_in = logged_in,
+               edit_url = edit_url)
 
 Adding the ``login.pt`` Template
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/tutorials/bfgwiki2/background.rst b/docs/tutorials/bfgwiki2/background.rst
index 2a0cd3f0f..31cecdf96 100644
--- a/docs/tutorials/bfgwiki2/background.rst
+++ b/docs/tutorials/bfgwiki2/background.rst
@@ -12,6 +12,6 @@ To code along with this tutorial, the developer will need a UNIX
 machine with development tools (Mac OS X with XCode, any Linux or BSD
 variant, etc) *or* he will need a Windows system of any kind.
 
-This tutorial is known to work under :mod:`repoze.bfg` version 1.0b1.
+This tutorial is known to work under :mod:`repoze.bfg` version 1.1a5.
 
 Have fun!
diff --git a/docs/tutorials/bfgwiki2/basiclayout.rst b/docs/tutorials/bfgwiki2/basiclayout.rst
index 9efee63a7..1cdcd425e 100644
--- a/docs/tutorials/bfgwiki2/basiclayout.rst
+++ b/docs/tutorials/bfgwiki2/basiclayout.rst
@@ -28,21 +28,25 @@ following:
 #. *Line 1*.  The root ``<configure>`` element, in a ``bfg``
    namespace.
 
-#. *Line 3*. Boilerplate, the comment explains.
+#. *Line 4*. Boilerplate, the comment explains.
 
 #. *Lines 6-7*.  Register a :term:`subscriber` that tears down the
    SQLAlchemy connection after a request is finished.
 
-#. *Lines 9-12*.  Register a ``<route>`` that will be used when the
+#. *Lines 9-13*.  Register a ``<route>`` that will be used when the
    URL is ``/``.  Since this ``<route>`` has an empty ``path``
    attribute, it is the "default" route. The attribute named ``view``
    with the value ``.views.my_view`` is the dotted name to a
    *function* we write (generated by the ``bfg_routesalchemy``
    template) that is given a ``request`` object and which returns a
-   response.  You will use mostly ``<route>`` statements in a
-   :term:`URL dispatch` based application to map URLs to code.
-
-#. *Lines 14-17*.  Register a ``<static>`` directive that will match
+   response or a dictionary.  You will use mostly ``<route>``
+   statements in a :term:`URL dispatch` based application to map URLs
+   to code.  This ``route`` also names a ``renderer``, which is a
+   template which lives in the ``templates`` subdirectory of the
+   package.  When the ``.views.my_view`` view returns a dictionary,
+   a "renderer" will use this template to create a response.
+
+#. *Lines 15-18*.  Register a ``<static>`` directive that will match
    any URL hat starts with ``/static/``.  This will serve up static
    resources for us, in this case, at
    ``http://localhost:6543/static/`` and below.  With this
diff --git a/docs/tutorials/bfgwiki2/definingviews.rst b/docs/tutorials/bfgwiki2/definingviews.rst
index 6dbea104e..35e02b1cc 100644
--- a/docs/tutorials/bfgwiki2/definingviews.rst
+++ b/docs/tutorials/bfgwiki2/definingviews.rst
@@ -109,18 +109,13 @@ HTML containing various view and add links for WikiWords based on the
 content of our current page object.
 
 We then generate an edit URL (because it's easier to do here than in
-the template), and we call the
-``repoze.bfg.chameleon_zpt.render_template_to_response`` function with
-a number of arguments.  The first argument is the *relative* path to a
-:term:`Chameleon` ZPT template.  It is relative to the directory of
-the file in which we're creating the ``view_page`` function.  The
-``render_template_to_response`` function also accepts ``request``,
-``page``, ``content``, and ``edit_url`` as keyword arguments.  As a
-result, the template will be able to use these names to perform
-various rendering tasks.
-
-The result of ``render_template_to_response`` is returned to
-:mod:`repoze.bfg`.  Unsurprisingly, it is a response object.
+the template), and we return a dictionary with a number of arguments.
+The fact that this view returns a dictionary (as opposed to a
+:term:`response` object) is a cue to :mod:`repoze.bfg` that it should
+try to use a :term:`renderer` associated with the view configuration
+to render a template.  In our case, the template which will be
+rendered will be the ``templates/view.pt`` template, as per the
+configuration put into effect in ``configure.zcml``.
 
 The ``add_page`` view function
 ------------------------------
@@ -138,17 +133,17 @@ the page we'd like to add.  If our add view is invoked via,
 e.g. ``http://localhost:6543/add_page/SomeName``, the ``pagename``
 value in the matchdict will be ``SomeName``.
 
-If the view rendering is *not* a result of a form submission (if the
+If the view execution is *not* a result of a form submission (if the
 expression ``'form.submitted' in request.params`` is False), the view
 renders a template.  To do so, it generates a "save url" which the
 template use as the form post URL during rendering.  We're lazy here,
 so we're trying to use the same template (``templates/edit.pt``) for
 the add view as well as the page edit view, so we create a dummy Page
 object in order to satisfy the edit form's desire to have *some* page
-object exposed as ``page``, and we'll render the template to a
-response.
+object exposed as ``page``, and BFG will render the template
+associated with this view to a response.
 
-If the view rendering *is* a result of a form submission (if the
+If the view execution *is* a result of a form submission (if the
 expression ``'form.submitted' in request.params`` is True), we scrape
 the page body from the form data, create a Page object using the name
 in the matchdict ``pagename``, and obtain the page body from the
@@ -166,12 +161,12 @@ it also acts as the handler for the form it renders.  The
 will have a ``pagename`` key matching the name of the page the user
 wants to edit.
 
-If the view rendering is *not* a result of a form submission (if the
+If the view execution is *not* a result of a form submission (if the
 expression ``'form.submitted' in request.params`` is False), the view
 simply renders the edit form, passing the request, the page object,
 and a save_url which will be used as the action of the generated form.
 
-If the view rendering *is* a result of a form submission (if the
+If the view execution *is* a result of a form submission (if the
 expression ``'form.submitted' in request.params`` is True), the view
 grabs the ``body`` element of the request parameter and sets it as the
 ``data`` key in the matchdict.  It then redirects to the default view
@@ -346,3 +341,47 @@ the top of it that generates an exception (e.g. ``raise
 Exception('Forced Exception')``).  Then visit the error-raising view
 in a browser.  You should see an interactive exception handler in the
 browser which allows you to examine values in a post-mortem mode.
+
+Adding Tests
+============
+
+Since we've added a good bit of imperative code here, it's useful to
+define tests for the views we've created.  We'll change our tests.py
+module to look like this:
+
+.. literalinclude:: src/views/tutorial/tests.py
+   :linenos:
+   :language: python
+
+We can then run the tests using something like:
+
+.. code-block:: bash
+   :linenos:
+
+   $ python setup.py test -q
+
+The expected output is something like:
+
+.. code-block:: bash
+   :linenos:
+
+   running test
+   running egg_info
+   writing requirements to tutorial.egg-info/requires.txt
+   writing tutorial.egg-info/PKG-INFO
+   writing top-level names to tutorial.egg-info/top_level.txt
+   writing dependency_links to tutorial.egg-info/dependency_links.txt
+   writing entry points to tutorial.egg-info/entry_points.txt
+   unrecognized .svn/entries format in 
+   reading manifest file 'tutorial.egg-info/SOURCES.txt'
+   writing manifest file 'tutorial.egg-info/SOURCES.txt'
+   running build_ext
+   ......
+   ----------------------------------------------------------------------
+   Ran 6 tests in 0.181s
+
+   OK
+
+
+
+