Merge remote branch 'source/master'

Conflicts:
	docs/narr/hooks.rst

1 files changed, 145 insertions, 137 deletions

diff --git a/docs/tutorials/wiki2/definingviews.rst b/docs/tutorials/wiki2/definingviews.rst
index e3d611136..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,38 +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".  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 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
+
+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
 -------------------------------
@@ -101,88 +106,95 @@ attribute of a Page object) as HTML.  Then it substitutes an HTML
 anchor for each *WikiWord* reference in the rendered HTML using a
 compiled regular expression.
 
+.. literalinclude:: src/views/tutorial/views.py
+   :pyobject: view_page
+   :linenos:
+   :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 ``add_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
+   :linenos:
+   :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.
-
-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 ``body`` element of the request parameter and sets it
-as the ``data`` key in the matchdict.  It then redirects to the
-default view of the wiki page, which will always be the ``view_page``
-view.
-
-Viewing the Result of Our Edits to ``views.py``
-===============================================
+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
+``body`` element of the request parameter and sets it as the ``data``
+attribute of the page object.  It then redirects to the default view of the
+wiki page, which will always be the ``view_page`` view.
+
+Viewing the Result of all Our Edits to ``views.py``
+===================================================
 
 The result of all of our edits to ``views.py`` will leave it looking
 like this:
@@ -201,18 +213,16 @@ 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
-   :linenos:
    :language: xml
 
 .. note:: The names available for our use in a template are always
@@ -228,37 +238,35 @@ 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:
 
 .. literalinclude:: src/views/tutorial/templates/edit.pt
-   :linenos:
    :language: xml
 
-Static Resources
-----------------
-
-Our templates name a single static resource named ``style.css``.  We need to
-create this and place it in a file named ``style.css`` within our package's
-``static`` directory.  This file is a little too long to replicate within the
-body of this guide, however it is available `online
-<http://github.com/Pylons/pyramid/blob/master/docs/tutorials/wiki2/src/views/tutorial/static/style.css>`_.
+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
+<http://github.com/Pylons/pyramid/blob/master/docs/tutorials/wiki2/src/views/tutorial/static/pylons.css>`_.
 
 This CSS file will be accessed via
-e.g. ``http://localhost:6543/static/style.css`` by virtue of the call we've
-made to :meth:`pyramid.config.Configurator.add_static_view` within our
-``__init__.py`` file.  Any number and type of static resources can be placed
-in this directory (or subdirectories) and are just referred to by URL within
-templates.
+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.
 
 Mapping Views to URLs in ``__init__.py``
 ========================================