Merge branch 'docs.quicktutorial'

1 files changed, 120 insertions, 0 deletions

diff --git a/docs/quick_tutorial/views.rst b/docs/quick_tutorial/views.rst
new file mode 100644
index 000000000..0902c45dd
--- /dev/null
+++ b/docs/quick_tutorial/views.rst
@@ -0,0 +1,120 @@
+=================================
+07: Basic Web Handling With Views
+=================================
+
+Organize a views module with decorators and multiple views.
+
+Background
+==========
+
+For the examples so far, the ``hello_world`` function is a "view". In
+Pyramid, views are the primary way to accept web requests and return
+responses.
+
+So far our examples place everything in one file:
+
+- The view function
+
+- Its registration with the configurator
+
+- The route to map it to a URL
+
+- The WSGI application launcher
+
+Let's move the views out to their own ``views.py`` module and change
+our startup code to scan that module, looking for decorators that setup
+the views. Let's also add a second view and update our tests.
+
+Objectives
+==========
+
+- Views in a module that is scanned by the configurator
+
+- Decorators that do declarative configuration
+
+Steps
+=====
+
+#. Let's begin by using the previous package as a starting point for a
+   new distribution, then making it active:
+
+   .. code-block:: bash
+
+    (venv)$ cd ..; cp -r function_testing views; cd views
+    (venv)$ python setup.py develop
+
+#. Our ``views/tutorial/__init__.py`` gets a lot shorter:
+
+   .. literalinclude:: views/tutorial/__init__.py
+    :linenos:
+
+#. Let's add a module ``views/tutorial/views.py`` that is focused on
+   handling requests and responses:
+
+   .. literalinclude:: views/tutorial/views.py
+    :linenos:
+
+#. Update the tests to cover the two new views:
+
+   .. literalinclude:: views/tutorial/tests.py
+    :linenos:
+
+#. Now run the tests:
+
+   .. code-block:: bash
+
+
+    (venv)$ nosetests tutorial
+    .
+    ----------------------------------------------------------------------
+    Ran 4 tests in 0.141s
+
+    OK
+
+#. Run your Pyramid application with:
+
+   .. code-block:: bash
+
+    (venv)$ pserve development.ini --reload
+
+#. Open http://localhost:6543/ and http://localhost:6543/howdy
+   in your browser.
+
+Analysis
+========
+
+We added some more URLs, but we also removed the view code from the
+application startup code in ``tutorial/__init__.py``.
+Our views, and their view registrations (via decorators) are now in a
+module ``views.py`` which is scanned via ``config.scan('.views')``.
+
+We have 2 views, each leading to the other. If you start at
+http://localhost:6543/, you get a response with a link to the next
+view. The ``hello_view`` (available at the URL ``/howdy``) has a link
+back to the first view.
+
+This step also shows that the name appearing in the URL,
+the name of the "route" that maps a URL to a view,
+and the name of the view, can all be different. More on routes later.
+
+Earlier we saw ``config.add_view`` as one way to configure a view. This
+section introduces ``@view_config``. Pyramid's configuration supports
+:term:`imperative configuration`, such as the
+``config.add_view`` in the previous example. You can also use
+:term:`declarative configuration`, in which a Python
+:term:`python:decorator`
+is placed on the line above the view. Both approaches result in the
+same final configuration, thus usually, it is simply a matter of taste.
+
+Extra Credit
+============
+
+#. What does the dot in ``.views`` signify?
+
+#. Why might ``assertIn`` be a better choice in testing the text in
+   responses than ``assertEqual``?
+
+.. seealso:: :ref:`views_chapter`,
+   :ref:`view_config_chapter`, and
+   :ref:`debugging_view_configuration`
+