Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Wording improvements to wiki2 tutorial for clarity #483

Merged
merged 2 commits into from

2 participants

@audreyr

Minor wording improvements to the Defining Views section of the SQLAlchemy + URL Dispatch Wiki Tutorial.

@mcdonc mcdonc merged commit a9aed5f into Pylons:master
@mcdonc
Owner

Woot.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
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,8 +107,8 @@ 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
@@ -111,18 +116,19 @@ a URL which represents the path to our "FrontPage".
: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,8 +153,8 @@ 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``.
@@ -156,11 +162,11 @@ 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
Something went wrong with that request. Please try again.