Skip to content
Browse files

Merge pull request #483 from audreyr/master

Wording improvements to wiki2 tutorial for clarity
  • Loading branch information...
2 parents 0d57eb6 + 0396003 commit a9aed5f471ceddc4dfaa6781455b0429389f3da1 @mcdonc mcdonc committed Mar 13, 2012
Showing with 37 additions and 31 deletions.
  1. +37 −31 docs/tutorials/wiki2/definingviews.rst
View
68 docs/tutorials/wiki2/definingviews.rst
@@ -26,19 +26,19 @@ Declaring Dependencies in Our ``setup.py`` File
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 added)
+(Only the highlighted line needs to be added.)
Running ``setup.py develop``
============================
@@ -72,22 +72,27 @@ like::
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
+
+(The highlighted lines are the ones that need to be added or edited.)
-We've gotten rid of the ``my_view`` view function and its decorator that was
+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,27 +107,28 @@ afterward.
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
:lines: 18-21
: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 +139,12 @@ compiled regular expression.
: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,20 +153,20 @@ our current page object.
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``.
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 +199,7 @@ newly created page.
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 +264,7 @@ and a submit button that has the name "form.submitted". The textarea in the
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

0 comments on commit a9aed5f

Please sign in to comment.
Something went wrong with that request. Please try again.