Wording improvements to Defining Views section of tutorial.

Audrey Roy

2012-03-14 04df1056cdadf1420e75d8bbbe81a384041ab0f7

Wording improvements to Defining Views section of tutorial.

 docs/tutorials/wiki2/definingviews.rst

@@ -26,17 +26,19 @@
The view code in our application will depend on a package which is not a
dependency of the original "tutorial" application.  The original "tutorial"
application was generated by the ``pcreate`` command; it doesn't know
about our custom application requirements.  We need to add a dependency on
the ``docutils`` package to our ``tutorial`` package's ``setup.py`` file by
assigning this dependency to the ``requires`` parameter in the
``setup`` function.
about our custom application requirements.  

We need to add a dependency on the ``docutils`` package to our ``tutorial``
package's ``setup.py`` file by assigning this dependency to the ``requires`` parameter in ``setup()``.

Open ``tutorial/setup.py`` and edit it to look like the following:

.. literalinclude:: src/views/setup.py
   :linenos:
   :emphasize-lines: 17
   :language: python
   :emphasize-lines: 17

(Only the highlighted line needs to be changed.)

(Only the highlighted line needs to be added)

@@ -72,22 +74,27 @@
Changing the ``views.py`` File
==============================

We're going to edit our ``views.py`` in a rather major way.  The result of
all of our edits to ``views.py`` will leave it looking like this:
It's time for a major change.  Open ``tutorial/tutorial/views.py`` and edit it to look like the following:

.. literalinclude:: src/views/tutorial/views.py
   :linenos:
   :language: python
   :emphasize-lines: 1-7,12,15-70

We've gotten rid of the ``my_view`` view function and its decorator that was
(The highlighted lines are the ones that need to be added or edited.)

We got rid of the ``my_view`` view function and its decorator that was
added when we originally rendered the ``alchemy`` scaffold.  It was only an
example and isn't relevant to our application.

Then we added four :term:`view callable` functions to our ``views.py``
module.  One view callable (named ``view_wiki``) will display the wiki itself
(it will answer on the root URL), another named ``view_page`` will display an
individual page, another named ``add_page`` will allow a page to be added,
and a final view callable named ``edit_page`` will allow a page to be edited.
module: 

* ``view_wiki()`` - Displays the wiki itself. It will answer on the root URL.
* ``view_page()`` - Displays an individual page.
* ``add_page()`` - Allows the user to add a page.
* ``edit_page()`` - Allows the user to edit a page.

We'll describe each one briefly and show the resulting ``views.py`` file
afterward.

@@ -102,8 +109,8 @@
The ``view_wiki`` view function
-------------------------------

The ``view_wiki`` function is the :term:`default view` that will be called
when a request is made to the root URL of our wiki.  It always redirects to
``view_wiki()`` is the :term:`default view` that gets called when a request 
is made to the root URL of our wiki.  It always redirects to
a URL which represents the path to our "FrontPage".

.. literalinclude:: src/views/tutorial/views.py
@@ -111,18 +118,19 @@
   :linenos:
   :language: python

The ``view_wiki`` function returns an instance of the
``view_wiki()`` returns an instance of the
:class:`pyramid.httpexceptions.HTTPFound` class (instances of which implement
the :class:`pyramid.interfaces.IResponse` interface like
:class:`pyramid.response.Response` does), It will use the
:meth:`pyramid.request.Request.route_url` API to construct a URL to the
``FrontPage`` page (e.g. ``http://localhost:6543/FrontPage``), and will use
it as the "location" of the HTTPFound response, forming an HTTP redirect.
:class:`pyramid.response.Response` does).

It uses the :meth:`pyramid.request.Request.route_url` API to construct a 
URL to the ``FrontPage`` page (e.g. ``http://localhost:6543/FrontPage``), which 
is used as the "location" of the HTTPFound response, forming an HTTP redirect.

The ``view_page`` view function
-------------------------------

The ``view_page`` function will be used to show a single page of our
``view_page()`` is used to display a single page of our
wiki.  It renders the :term:`ReStructuredText` body of a page (stored as
the ``data`` attribute of a Page object) as HTML.  Then it substitutes an
HTML anchor for each *WikiWord* reference in the rendered HTML using a
@@ -133,12 +141,12 @@
   :linenos:
   :language: python

The curried function named ``check`` is used as the first argument to
The curried ``check()`` function is used as the first argument to
``wikiwords.sub``, indicating that it should be called to provide a value for
each WikiWord match found in the content.  If the wiki already contains a
page with the matched WikiWord name, the ``check`` function generates a view
page with the matched WikiWord name, ``check()`` generates a view
link to be used as the substitution value and returns it.  If the wiki does
not already contain a page with with the matched WikiWord name, the function
not already contain a page with with the matched WikiWord name, ``check()``
generates an "add" link as the substitution value and returns it.

As a result, the ``content`` variable is now a fully formed bit of HTML
@@ -147,8 +155,8 @@

We then generate an edit URL (because it's easier to do here than in 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 :app:`Pyramid` that it should try to use a :term:`renderer`
that ``view_page()`` returns a dictionary (as opposed to a :term:`response`
object) is a cue to :app:`Pyramid` 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 ``__init__.py``.
@@ -156,11 +164,11 @@
The ``add_page`` view function
------------------------------

The ``add_page`` function will be invoked when a user clicks on a *WikiWord*
which isn't yet represented as a page in the system.  The ``check`` function
``add_page()`` is invoked when a user clicks on a *WikiWord* which isn't yet
represented as a page in the system.  The ``check`` function
within the ``view_page`` view generates URLs to this view.  It also acts as a
handler for the form that is generated when we want to add a page object.
The ``matchdict`` attribute of the request passed to the ``add_page`` view
The ``matchdict`` attribute of the request passed to the ``add_page()`` view
will have the values we need to construct URLs and find model objects.

.. literalinclude:: src/views/tutorial/views.py
@@ -193,7 +201,7 @@
The ``edit_page`` view function
-------------------------------

The ``edit_page`` function will be invoked when a user clicks the "Edit this
``edit_page()`` is invoked when a user clicks the "Edit this
Page" button on the view form.  It renders an edit form but it also acts as
the handler for the form it renders.  The ``matchdict`` attribute of the
request passed to the ``edit_page`` view will have a ``'pagename'`` key
@@ -258,7 +266,7 @@
form should be filled with any existing page data when it is rendered.

Once we're done with the ``edit.pt`` template, it will look a lot like
the below:
the following:

.. literalinclude:: src/views/tutorial/templates/edit.pt
   :language: xml