From 6ed41a034df40dcc6632432544742ebefe3162ba Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 20 Mar 2011 18:08:58 -0400 Subject: review changes to sqla tutorial --- docs/tutorials/wiki2/definingviews.rst | 223 ++++++++++++++++----------------- 1 file changed, 106 insertions(+), 117 deletions(-) (limited to 'docs/tutorials/wiki2/definingviews.rst') diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst index 3fa9bbccd..874c49d4c 100644 --- a/docs/tutorials/wiki2/definingviews.rst +++ b/docs/tutorials/wiki2/definingviews.rst @@ -2,10 +2,10 @@ Defining Views ============== -A :term:`view callable` in a :term:`url dispatch` -based -:app:`Pyramid` application is typically a simple Python function that -accepts a single parameter named :term:`request`. A view callable is -assumed to return a :term:`response` object. +A :term:`view callable` in a :term:`url dispatch` -based :app:`Pyramid` +application is typically a simple Python function that accepts a single +parameter named :term:`request`. A view callable is assumed to return a +:term:`response` object. .. note:: A :app:`Pyramid` view can also be defined as callable which accepts *two* arguments: a :term:`context` and a @@ -23,11 +23,11 @@ assumed to return a :term:`response` object. The request passed to every view that is called as the result of a route match has an attribute named ``matchdict`` that contains the elements placed into the URL by the ``pattern`` of a ``route`` statement. For instance, if a -call to :meth:`pyramid.config.Configurator.add_route` in -``__init__.py`` had the pattern ``{one}/{two}``, and the URL at -``http://example.com/foo/bar`` was invoked, matching this pattern, the -matchdict dictionary attached to the request passed to the view would have a -``one`` key with the value ``foo`` and a ``two`` key with the value ``bar``. +call to :meth:`pyramid.config.Configurator.add_route` in ``__init__.py`` had +the pattern ``{one}/{two}``, and the URL at ``http://example.com/foo/bar`` +was invoked, matching this pattern, the matchdict dictionary attached to the +request passed to the view would have a ``one`` key with the value ``foo`` +and a ``two`` key with the value ``bar``. The source code for this tutorial stage can be browsed at `http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki2/src/views/ @@ -36,13 +36,13 @@ The source code for this tutorial stage can be browsed at 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 ``paster create`` 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 -``install_requires`` parameter in the ``setup`` function. +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 ``paster create`` 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 ``install_requires`` parameter in the +``setup`` function. Our resulting ``setup.py`` should look like so: @@ -58,45 +58,43 @@ Our resulting ``setup.py`` should look like so: Adding View Functions ===================== -We'll get rid of our ``my_view`` view function in our ``views.py`` -file. It's only an example and isn't relevant to our application. +We'll get rid of our ``my_view`` view function in our ``views.py`` file. +It's only an example and isn't relevant to our application. Then we're going to add 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. We'll describe -each one briefly and show the resulting ``views.py`` file afterward. +``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. We'll describe each one briefly and show the resulting +``views.py`` file afterward. .. note:: - There is nothing special about the filename ``views.py``. A project - may have many view callables throughout its codebase in - arbitrarily-named files. Files implementing view callables often - have ``view`` in their filenames (or may live in a Python subpackage - of your application package named ``views``), but this is only by - convention. + There is nothing special about the filename ``views.py``. A project may + have many view callables throughout its codebase in arbitrarily-named + files. Files implementing view callables often have ``view`` in their + filenames (or may live in a Python subpackage of your application package + named ``views``), but this is only by convention. The ``view_wiki`` view function ------------------------------- -The ``view_wiki`` function will respond as the :term:`default view` of -a ``Wiki`` model object. It always redirects to a URL which -represents the path to our "FrontPage". +The ``view_wiki`` function will respond as the :term:`default view` of a +``Wiki`` model object. It always redirects to a URL which represents the +path to our "FrontPage". .. literalinclude:: src/views/tutorial/views.py :pyobject: view_wiki :linenos: :language: python -It returns an instance of the -:class:`pyramid.httpexceptions.HTTPFound` class (instances of which -implement the WebOb :term:`response` interface), It will use the -:func:`pyramid.url.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. +The ``view_wiki`` function returns an instance of the +:class:`pyramid.httpexceptions.HTTPFound` class (instances of which implement +the WebOb :term:`response` interface), It will use the +:func:`pyramid.url.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. The ``view_page`` view function ------------------------------- @@ -114,76 +112,70 @@ compiled regular expression. :language: python 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, the ``check`` -function 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 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 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 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` 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``. +``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 +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 +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 +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 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` +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 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 will have the values we need -to construct URLs and find model objects. +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 +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 +will have the values we need to construct URLs and find model objects. .. literalinclude:: src/views/tutorial/views.py :pyobject: add_page :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 ``pagename`` -value in the matchdict will be ``SomeName``. +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 ``pagename`` value in +the matchdict will be ``SomeName``. If the view execution is *not* a result of a form submission (if the -expression ``'form.submitted' in request.params`` is ``False``), the -view callable 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 -:app:`Pyramid` will render the template associated with this view -to a response. - -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 request, and save it into the database using ``session.add``. We -then redirect back to the ``view_page`` view (the :term:`default view` -for a Page) for the newly created page. +expression ``'form.submitted' in request.params`` is ``False``), the view +callable 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 :app:`Pyramid` will render the template associated with this +view to a response. + +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 request, and save it into the +database using ``session.add``. We then redirect back to the ``view_page`` +view (the :term:`default view` for a Page) for the newly created page. The ``edit_page`` view function ------------------------------- -The ``edit_page`` function will be 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. +The ``edit_page`` function will be 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. .. literalinclude:: src/views/tutorial/views.py :pyobject: edit_page @@ -191,10 +183,9 @@ wants to edit. :language: python 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. +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 execution *is* a result of a form submission (if the expression ``'form.submitted' in request.params`` is ``True``), the view grabs the @@ -222,15 +213,14 @@ The views we've added all reference a :term:`template`. Each template is a The ``view.pt`` Template ------------------------ -The ``view.pt`` template is used for viewing a single wiki page. It -is used by the ``view_page`` view function. It should have a div that -is "structure replaced" with the ``content`` value provided by the -view. It should also have a link on the rendered page that points at -the "edit" URL (the URL which invokes the ``edit_page`` view for the -page being viewed). +The ``view.pt`` template is used for viewing a single wiki page. It is used +by the ``view_page`` view function. It should have a div that is "structure +replaced" with the ``content`` value provided by the view. It should also +have a link on the rendered page that points at the "edit" URL (the URL which +invokes the ``edit_page`` view for the page being viewed). -Once we're done with the ``view.pt`` template, it will look a lot like -the below: +Once we're done with the ``view.pt`` template, it will look a lot like the +below: .. literalinclude:: src/views/tutorial/templates/view.pt :language: xml @@ -248,13 +238,12 @@ the below: The ``edit.pt`` Template ------------------------ -The ``edit.pt`` template is used for adding and editing a wiki page. -It is used by the ``add_page`` and ``edit_page`` view functions. It -should display a page containing a form that POSTs back to the -"save_url" argument supplied by the view. The form should have a -"body" textarea field (the page data), 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. +The ``edit.pt`` template is used for adding and editing a wiki page. It is +used by the ``add_page`` and ``edit_page`` view functions. It should display +a page containing a form that POSTs back to the "save_url" argument supplied +by the view. The form should have a "body" textarea field (the page data), +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: @@ -267,8 +256,8 @@ Static Assets Our templates name a single static asset named ``pylons.css``. We don't need to create this file within our package's ``static`` directory because it was -provided at the time we created the project. This file is a little too long to -replicate within the body of this guide, however it is available `online +provided at the time we created the project. This file is a little too long +to replicate within the body of this guide, however it is available `online `_. This CSS file will be accessed via @@ -276,8 +265,8 @@ e.g. ``http://localhost:6543/static/pylons.css`` by virtue of the call to ``add_static_view`` directive we've made in the ``__init__`` file. Any number and type of static assets can be placed in this directory (or subdirectories) and are just referred to by URL or by using the convenience -method ``static_url`` e.g. ``request.static_url('{{package}}:static/foo.css')`` -within templates. +method ``static_url`` +e.g. ``request.static_url('{{package}}:static/foo.css')`` within templates. Mapping Views to URLs in ``__init__.py`` ======================================== -- cgit v1.2.3