Merge branch 'master' into viewderiver

1 files changed, 128 insertions, 64 deletions

diff --git a/docs/tutorials/wiki/basiclayout.rst b/docs/tutorials/wiki/basiclayout.rst
index c7c722f70..f6e1f800a 100644
--- a/docs/tutorials/wiki/basiclayout.rst
+++ b/docs/tutorials/wiki/basiclayout.rst
@@ -2,10 +2,9 @@
 Basic Layout
 ============
 
-The starter files generated by the ``pyramid_zodb`` template are basic,
-but they provide a good orientation for the high-level patterns common
-to most :term:`traversal` -based :app:`Pyramid` (and :term:`ZODB`
-based) projects.
+The starter files generated by the ``pyramid_zodb`` template are basic, but
+they provide a good orientation for the high-level patterns common to most
+:term:`traversal` -based :app:`Pyramid` (and :term:`ZODB` based) projects.
 
 The source code for this tutorial stage can be browsed via
 `http://github.com/Pylons/pyramid/tree/master/docs/tutorials/wiki/src/basiclayout/
@@ -21,9 +20,9 @@ well as to contain application configuration code.
 
 When you run the application using the ``paster`` command using the
 ``development.ini`` generated config file, the application configuration
-points at an Setuptools *entry point* described as ``egg:tutorial#app``.  In
-our application, because the application's ``setup.py`` file says so, this
-entry point happens to be the ``app`` function within the file named
+points at an Setuptools *entry point* described as ``egg:tutorial``.  In our
+application, because the application's ``setup.py`` file says so, this entry
+point happens to be the ``main`` function within the file named
 ``__init__.py``:
 
    .. literalinclude:: src/basiclayout/tutorial/__init__.py
@@ -48,65 +47,40 @@ entry point happens to be the ``app`` function within the file named
    factory` and the settings keywords parsed by PasteDeploy.  The root
    factory is named ``get_root``.
 
-#. *Line 16*.  Load the
-   ``configure.zcml`` file from our package using the
-   :meth:`pyramid.config.Configurator.load_zcml` method.
-
-#. *Line 17*.  Use the
+#. *Line 16*.  Register a 'static view' which answers requests which start
+   with with URL path ``/static`` using the
+   :meth:`pyramid.config.Configurator.add_static_view method`.  This
+   statement registers a view that will serve up static assets, such as CSS
+   and image files, for us, in this case, at
+   ``http://localhost:6543/static/`` and below.  The first argument is the
+   "name" ``static``, which indicates that the URL path prefix of the view
+   will be ``/static``.  the The second argument of this tag is the "path",
+   which is an :term:`asset specification`, so it finds the resources it
+   should serve within the ``static`` directory inside the ``tutorial``
+   package.
+
+#. *Line 17*.  Perform a :term:`scan`.  A scan will find :term:`configuration
+   decoration`, such as view configuration decorators
+   (e.g. ``@view_config``) in the source code of the ``tutorial`` package and
+   will take actions based on these decorators.  The argument to
+   :meth:`~pyramid.config.Configurator.scan` is the package name to scan,
+   which is ``tutorial``.
+
+#. *Line 18*.  Use the
    :meth:`pyramid.config.Configurator.make_wsgi_app` method
    to return a :term:`WSGI` application.
 
-Configuration With ``configure.zcml``
---------------------------------------
-
-The ``pyramid_zodb`` template uses :term:`ZCML` to perform system
-configuration.  The ZCML file generated by the template looks like the
-following:
-
-   .. literalinclude:: src/basiclayout/tutorial/configure.zcml
-      :linenos:
-      :language: xml
-
-#. *Line 1*.  The root ``<configure>`` element.
-
-#. *Line 4*. Boilerplate, the comment explains.
-
-#. *Lines 6-10*.  Register a ``<view>`` that names a ``context`` type
-   that is a class.  ``.views.my_view`` is a *function* we write
-   (generated by the ``pyramid_zodb`` template) that is given a
-   ``context`` object and a ``request`` and which returns a
-   dictionary.  The ``renderer`` tag indicates that the
-   ``templates/mytemplate.pt`` template should be used to turn the
-   dictionary returned by the view into a response.
-   ``templates/mytemplate.pt`` is a *relative* path: it names the
-   ``mytemplate.pt`` file which lives in the ``templates``
-   subdirectory of the directory in which this ``configure.zcml``
-   lives in.  In this case, it means it lives in the ``tutorial``
-   package's ``templates`` directory as ``mytemplate.pt``
-
-   Since this ``<view>`` doesn't have a ``name`` attribute, it is the
-   "default" view for that class.
-
-#. *Lines 12-15*.  Register a ``static`` view which answers requests
-   which start with ``/static``.  This is a view that will serve up
-   static resources for us, in this case, at
-   ``http://localhost:6543/static/`` and below.  The ``path`` element
-   of this tag is a relative directory name, so it finds the resources
-   it should serve within the ``static`` directory inside
-   the ``tutorial`` package.
-
-Content Models with ``models.py``
----------------------------------
+Resources and Models with ``models.py``
+---------------------------------------
 
 :app:`Pyramid` uses the word :term:`resource` to describe objects arranged
 hierarchically in a :term:`resource tree`.  This tree is consulted by
 :term:`traversal` to map URLs to code.  In this application, the resource
 tree represents the site structure, but it *also* represents the
-:term:`domain model` of the application, because eeach resource is a node
+:term:`domain model` of the application, because each resource is a node
 stored persistently in a :term:`ZODB` database.  The ``models.py`` file is
 where the ``pyramid_zodb`` Paster template put the classes that implement our
-resource objects, each of which happens also to be a domain model
-object.
+resource objects, each of which happens also to be a domain model object.
 
 Here is the source for ``models.py``:
 
@@ -114,14 +88,13 @@ Here is the source for ``models.py``:
       :linenos:
       :language: py
 
-#. *Lines 3-4*.  The ``MyModel`` class we referred to in the ZCML file
-   named ``configure.zcml`` is implemented here.  Instances of this
-   class will be capable of being persisted in :term:`ZODB` because
-   the class inherits from the
-   :class:`persistent.mapping.PersistentMapping` class.  The
-   ``__parent__`` and ``__name__`` are important parts of the
-   :term:`traversal` protocol.  By default, have these as ``None``
-   indicating that this is the :term:`root` object.
+#. *Lines 3-4*.  The ``MyModel`` :term:`resource` class is implemented here.
+   Instances of this class will be capable of being persisted in :term:`ZODB`
+   because the class inherits from the
+   :class:`persistent.mapping.PersistentMapping` class.  The ``__parent__``
+   and ``__name__`` are important parts of the :term:`traversal` protocol.
+   By default, have these as ``None`` indicating that this is the
+   :term:`root` object.
 
 #. *Lines 6-12*.  ``appmaker`` is used to return the *application
    root* object.  It is called on *every request* to the
@@ -134,3 +107,94 @@ Here is the source for ``models.py``:
    commit the transaction.  We then return the application root
    object.
 
+Views With ``views.py``
+-----------------------
+
+Our paster template generated a default ``views.py`` on our behalf.  It
+contains a single view, which is used to render the page shown when you visit
+the URL ``http://localhost:6543/``.
+
+Here is the source for ``views.py``:
+
+   .. literalinclude:: src/basiclayout/tutorial/views.py
+      :linenos:
+      :language: py
+
+Let's try to understand the components in this module:
+
+#. *Lines 1-2*. Perform some dependency imports.
+
+#. *Line 4*.  Use the :func:`pyramid.view.view_config` :term:`configuration
+   decoration` to perform a :term:`view configuration` registration.  This
+   view configuration registration will be activated when the application is
+   started.  It will be activated by virtue of it being found as the result
+   of a :term:`scan` (when Line 17 of ``__init__.py`` is run).
+
+   The ``@view_config`` decorator accepts a number of keyword arguments.  We
+   use two keyword arguments here: ``context`` and ``renderer``.
+
+   The ``context`` argument signifies that the decorated view callable should
+   only be run when :term:`traversal` finds the ``tutorial.models.MyModel``
+   :term:`resource` to be the :term:`context` of a request.  In English, this
+   means that when the URL ``/`` is visited, because ``MyModel`` is the root
+   model, this view callable will be invoked.
+
+   The ``renderer`` argument names an :term:`asset specification` of
+   ``tutorial:templates/mytemplate.pt``.  This asset specification points at
+   a :term:`Chameleon` template which lives in the ``mytemplate.pt`` file
+   within the ``templates`` directory of the ``tutorial`` package.  And
+   indeed if you look in the ``templates`` directory of this package, you'll
+   see a ``mytemplate.pt`` template file, which renders the default home page
+   of the generated project.
+
+   Since this call to ``@view_config`` doesn't pass a ``name`` argument, the
+   ``my_view`` function which it decorates represents the "default" view
+   callable used when the context is of the type ``MyModel``.
+
+#. *Lines 5-6*.  We define a :term:`view callable` named ``my_view``, which
+   we decorated in the step above.  This view callable is a *function* we
+   write generated by the ``pyramid_zodb`` template that is given a
+   ``request`` and which returns a dictionary.  The ``mytemplate.pt``
+   :term:`renderer` named by the asset specification in the step above will
+   convert this dictionary to a :term:`response` on our behalf.
+
+   The function returns the dictionary ``{'project':'tutorial'}``.  This
+   dictionary is used by the template named by the ``mytemplate.pt`` asset
+   specification to fill in certain values on the page.
+
+The WSGI Pipeline in ``development.ini``
+----------------------------------------
+
+The ``development.ini`` (in the tutorial :term:`project` directory, as
+opposed to the tutorial :term:`package` directory) looks like this:
+
+.. literalinclude:: src/views/development.ini
+   :linenos:
+   :language: ini
+
+
+Note the existence of a ``[pipeline:main]`` section which specifies our WSGI
+pipeline.  This "pipeline" will be served up as our WSGI application.  As far
+as the WSGI server is concerned the pipeline *is* our application.  Simpler
+configurations don't use a pipeline: instead they expose a single WSGI
+application as "main".  Our setup is more complicated, so we use a pipeline
+composed of :term:`middleware`.
+
+The ``egg:WebError#evalerror`` middleware is at the "top" of the pipeline.
+This is middleware which displays debuggable errors in the browser while
+you're developing (not recommended for deployment).
+
+The ``egg:repoze.zodbconn#closer`` middleware is in the middle of the
+pipeline.  This is a piece of middleware which closes the ZODB connection
+opened by the ``PersistentApplicationFinder`` at the end of the request.
+
+The ``egg:repoze.tm#tm`` middleware is the last piece of middleware in the
+pipeline.  This commits a transaction near the end of the request unless
+there's an exception raised.
+
+The final line in the ``[pipeline:main]`` section is ``tutorial``, which
+refers to the ``[app:tutorial]`` section above it.  The ``[app:tutorial]``
+section is the section which actually defines our application settings.  The
+values within this section are passed as ``**settings`` to the ``main``
+function we defined in ``__init__.py`` when the server is started via
+``paster serve``.