diff options
Diffstat (limited to 'docs/tutorials/wiki2')
| -rw-r--r-- | docs/tutorials/wiki2/definingviews.rst | 163 |
1 files changed, 83 insertions, 80 deletions
diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index 0981af268..d7f63100d 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -23,26 +23,27 @@ 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 ``setup()``. +package's ``setup.py`` file by assigning this dependency to the ``requires`` +parameter in the ``setup()`` function. Open ``tutorial/setup.py`` and edit it to look like the following: .. literalinclude:: src/views/setup.py :linenos: - :language: python :emphasize-lines: 20 + :language: python Only the highlighted line needs to be added. Running ``setup.py develop`` ============================ -Since a new software dependency was added, you will need to rerun ``python -setup.py develop`` inside the root of the ``tutorial`` package to obtain and -register the newly added dependency distribution. +Since a new software dependency was added, you will need to run ``python +setup.py develop`` again inside the root of the ``tutorial`` package to obtain +and register the newly added dependency distribution. Make sure your current working directory is the root of the project (the -directory in which setup.py lives) and execute the following command. +directory in which ``setup.py`` lives) and execute the following command. On UNIX: @@ -63,21 +64,24 @@ like:: Finished processing dependencies for tutorial==0.0 -Changing the ``views.py`` File -============================== +Adding view functions in ``views.py`` +===================================== -It's time for a major change. Open ``tutorial/tutorial/views.py`` and edit it to look like the following: +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,14,16-72 -The highlighted lines are the ones that need to be added or edited. +The highlighted lines need to be added or edited. + +We added some imports and created a regular expression to find "WikiWords". -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. +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: @@ -87,8 +91,7 @@ module: * ``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. +We'll describe each one briefly in the following sections. .. note:: @@ -101,9 +104,7 @@ afterward. The ``view_wiki`` view function ------------------------------- -``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". +Following is the code for the ``view_wiki`` view function and its decorator: .. literalinclude:: src/views/tutorial/views.py :lines: 20-24 @@ -111,23 +112,23 @@ a URL which represents the path to our "FrontPage". :linenos: :language: python -``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). +``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 an URL which +represents the path to our "FrontPage". -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_wiki`` view callable always redirects to the URL of a Page resource +named "FrontPage". To do so, it 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 uses the +:meth:`pyramid.request.Request.route_url` API to construct an URL to the +``FrontPage`` page (i.e., ``http://localhost:6543/FrontPage``), and uses it as +the "location" of the ``HTTPFound`` response, forming an HTTP redirect. The ``view_page`` view function ------------------------------- -``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`` model object) as HTML. Then it substitutes an -HTML anchor for each *WikiWord* reference in the rendered HTML using a -compiled regular expression. +Here is the code for the ``view_page`` view function and its decorator: .. literalinclude:: src/views/tutorial/views.py :lines: 25-45 @@ -135,7 +136,12 @@ compiled regular expression. :linenos: :language: python -The ``check()`` function is used as the first argument to +``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`` model object) as HTML. Then it substitutes an HTML anchor for each +*WikiWord* reference in the rendered HTML using a compiled regular expression. + +The curried function named ``check`` 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, ``check()`` generates a view @@ -158,6 +164,14 @@ renderer used will be the ``templates/view.pt`` template, as indicated in the The ``add_page`` view function ------------------------------ +Here is the code for the ``add_page`` view function and its decorator: + +.. literalinclude:: src/views/tutorial/views.py + :lines: 47-58 + :lineno-start: 47 + :linenos: + :language: python + ``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. @@ -166,12 +180,6 @@ when we want to add a page object. 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 - :lines: 47-58 - :lineno-start: 47 - :linenos: - :language: python - The ``matchdict`` will have a ``'pagename'`` key that matches the name of the page we'd like to add. If our add view is invoked via, e.g., ``http://localhost:6543/add_page/SomeName``, the value for @@ -197,11 +205,7 @@ with this view to a response. The ``edit_page`` view function ------------------------------- -``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 -matching the name of the page the user wants to edit. +Here is the code for the ``edit_page`` view function and its decorator: .. literalinclude:: src/views/tutorial/views.py :lines: 60-72 @@ -209,6 +213,12 @@ matching the name of the page the user wants to edit. :linenos: :language: python +``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 +matching the name of the page the user wants to edit. + If the view execution *is* a result of a form submission (i.e., the expression ``'form.submitted' in request.params`` is ``True``), the view grabs the ``body`` element of the request parameters and sets it as the ``data`` @@ -220,16 +230,16 @@ expression ``'form.submitted' in request.params`` is ``False``), the view simply renders the edit form, passing the page object and a ``save_url`` which will be used as the action of the generated form. -Adding Templates +Adding templates ================ The ``view_page``, ``add_page`` and ``edit_page`` views that we've added -reference a :term:`template`. Each template is a :term:`Chameleon` :term:`ZPT` -template. These templates will live in the ``templates`` directory of our -tutorial package. Chameleon templates must have a ``.pt`` extension to be -recognized as such. +reference a :term:`template`. Each template is a :term:`Chameleon` +:term:`ZPT` template. These templates will live in the ``templates`` +directory of our tutorial package. Chameleon templates must have a ``.pt`` +extension to be recognized as such. -The ``view.pt`` Template +The ``view.pt`` template ------------------------ Create ``tutorial/tutorial/templates/view.pt`` and add the following @@ -242,15 +252,13 @@ content: This template is used by ``view_page()`` for displaying a single wiki page. It includes: -- A ``div`` element that is replaced with the ``content`` - value provided by the view (lines 36-38). ``content`` - contains HTML, so the ``structure`` keyword is used - to prevent escaping it (i.e., changing ">" to ">", etc.) -- A link that points - at the "edit" URL which invokes the ``edit_page`` view for - the page being viewed (lines 40-42). +- A ``div`` element that is replaced with the ``content`` value provided by + the view (lines 36-38). ``content`` contains HTML, so the ``structure`` + keyword is used to prevent escaping it (i.e., changing ">" to ">", etc.) +- A link that points at the "edit" URL which invokes the ``edit_page`` view + for the page being viewed (lines 40-42). -The ``edit.pt`` Template +The ``edit.pt`` template ------------------------ Create ``tutorial/tutorial/templates/edit.pt`` and add the following @@ -260,24 +268,21 @@ content: :linenos: :language: html -This template is used by ``add_page()`` and ``edit_page()`` for adding -and editing a wiki page. It displays a page containing a form that includes: +This template is used by ``add_page()`` and ``edit_page()`` for adding and +editing a wiki page. It displays a page containing a form that includes: - A 10 row by 60 column ``textarea`` field named ``body`` that is filled with any existing page data when it is rendered (line 45). - A submit button that has the name ``form.submitted`` (line 48). -The form POSTs back to the ``save_url`` argument supplied -by the view (line 43). The view will use the ``body`` and -``form.submitted`` values. +The form POSTs back to the ``save_url`` argument supplied by the view (line +43). The view will use the ``body`` and ``form.submitted`` values. -.. note:: Our templates use a ``request`` object that - none of our tutorial views return in their dictionary. - ``request`` is one of several - names that are available "by default" in a template when a template - renderer is used. See :ref:`renderer_system_values` for - information about other names that are available by default - when a template is used as a renderer. +.. note:: Our templates use a ``request`` object that none of our tutorial + views return in their dictionary. ``request`` is one of several names that + are available "by default" in a template when a template renderer is used. + See :ref:`renderer_system_values` for information about other names that + are available by default when a template is used as a renderer. Static Assets ------------- @@ -347,21 +352,19 @@ We can finally examine our application in a browser (See :ref:`wiki2-start-the-application`). Launch a browser and visit each of the following URLs, checking that the result is as expected: -- http://localhost:6543 in a browser invokes the - ``view_wiki`` view. This always redirects to the ``view_page`` view - of the FrontPage page object. +- ``http://localhost:6543/`` invokes the ``view_wiki`` view. This always + redirects to the ``view_page`` view of the ``FrontPage`` page object. -- http://localhost:6543/FrontPage in a browser invokes - the ``view_page`` view of the front page object. +- http://localhost:6543/FrontPage invokes the ``view_page`` view of the front + page object. -- http://localhost:6543/FrontPage/edit_page in a browser - invokes the edit view for the front page object. +- http://localhost:6543/FrontPage/edit_page invokes the edit view for the + front page object. -- http://localhost:6543/add_page/SomePageName in a - browser invokes the add view for a page. +- http://localhost:6543/add_page/SomePageName invokes the add view for a page. - To generate an error, visit http://localhost:6543/foobars/edit_page which - will generate a ``NoResultFound: No row was found for one()`` error. - You'll see an interactive traceback facility provided - by :term:`pyramid_debugtoolbar`. + will generate a ``NoResultFound: No row was found for one()`` error. You'll + see an interactive traceback facility provided by + :term:`pyramid_debugtoolbar`. |