From 97b64d3b736f6abf0d78126c75d5e56e774bd234 Mon Sep 17 00:00:00 2001
From: Paul Winkler <slinkp@gmail.com>
Date: Mon, 30 Jan 2012 17:34:51 -0500
Subject: Hello world with traversal, linked from various places; plus some
 'what this chapter is for' notes on the other traversal chapters. Hope this
 helps.

---
 docs/narr/hellotraversal.py  | 22 ++++++++++++++
 docs/narr/hellotraversal.rst | 69 ++++++++++++++++++++++++++++++++++++++++++++
 docs/narr/introduction.rst   |  2 +-
 docs/narr/traversal.rst      |  7 +++++
 4 files changed, 99 insertions(+), 1 deletion(-)
 create mode 100644 docs/narr/hellotraversal.py
 create mode 100644 docs/narr/hellotraversal.rst

(limited to 'docs/narr')

diff --git a/docs/narr/hellotraversal.py b/docs/narr/hellotraversal.py
new file mode 100644
index 000000000..1ef7525e6
--- /dev/null
+++ b/docs/narr/hellotraversal.py
@@ -0,0 +1,22 @@
+from wsgiref.simple_server import make_server
+from pyramid.config import Configurator
+from pyramid.response import Response
+
+class Resource(dict):
+    pass
+
+def get_root(request):
+    return Resource({'a': Resource({'b': Resource({'c': Resource()})})})
+
+def hello_world_of_resources(context, request):
+    output = "Here's a resource and its children: %s" % context
+    return Response(output)
+
+if __name__ == '__main__':
+    config = Configurator(root_factory=get_root)
+    config.add_view(hello_world_of_resources, context=Resource)
+    app = config.make_wsgi_app()
+    server = make_server('0.0.0.0', 8080, app)
+    server.serve_forever()
+
+
diff --git a/docs/narr/hellotraversal.rst b/docs/narr/hellotraversal.rst
new file mode 100644
index 000000000..142c24f54
--- /dev/null
+++ b/docs/narr/hellotraversal.rst
@@ -0,0 +1,69 @@
+.. _hello_traversal_chapter:
+
+Hello Traversal World
+======================
+
+
+.. index::
+   single: traversal quick example
+
+Traversal is an alternative to URL dispatch which allows Pyramid
+applications to map URLs to code.
+
+If code speaks louder than words, maybe this will help. Here is a
+single-file Pyramid application that uses traversal:
+
+.. literalinclude:: hellotraversal.py
+   :linenos:
+
+You may notice that this application is intentionally very similar to
+the "hello world" app from :doc:`firstapp`.
+
+On lines 5-6, we create a trivial :term:`resource` class that's just a
+dictionary subclass.
+
+On lines 8-9, we hard-code a :term:`resource tree` in our :term:`root
+factory` function.
+
+On lines 11-13 we define a single :term:`view callable` that can
+display a single instance of our Resource class, passed as the
+``context`` argument.
+
+The rest of the file sets up and serves our pyramid WSGI app.  Line 18
+is where our view gets configured for use whenever the traversal ends
+with an instance of our Resource class.
+
+Interestingly, there are no URLs explicitly configured in this
+application. Instead, the URL space is defined entirely by the keys in
+the resource tree.
+
+Example requests
+----------------
+
+If this example is running on http://localhost:8080, and the user
+browses to http://localhost:8080/a/b, Pyramid will call
+``get_root(request)`` to get the root resource, then traverse the tree
+from there by key; starting from the root, it will find the child with
+key ``"a"``, then its child with key ``"b"``; then use that as the
+``context`` argument for calling ``hello_world_of_resources``.
+
+Or, if the user browses to http://localhost:8080/ , Pyramid will
+stop at the root - the outermost Resource instance, in this case - and
+use that as the ``context`` argument to the same view.
+
+Or, if the user browses to a key that doesn't exist in this resource
+tree, like http://localhost:8080/xyz or
+http://localhost:8080/a/b/c/d, the traversal will end by raising a
+KeyError, and Pyramid will turn that into a 404 HTTP response.
+
+A more complicated application could have many types of resources,
+with different view callables defined for each type, and even multiple
+views for each type.
+
+See Also
+---------
+
+Full technical details may be found in :doc:`traversal`.
+
+For more about *why* you might use traversal, see :doc:`muchadoabouttraversal`.
+
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 7c6ad00f3..92955aafd 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -597,7 +597,7 @@ content management systems and document management systems.  Traversal also lend
 systems that require very granular security ("Bob can edit *this* document"
 as opposed to "Bob can edit documents").
 
-Example: :ref:`much_ado_about_traversal_chapter`.
+Example: :ref:`hello_traversal_chapter` and :ref:`much_ado_about_traversal_chapter`.
 
 Tweens
 ~~~~~~
diff --git a/docs/narr/traversal.rst b/docs/narr/traversal.rst
index ef875c8f0..8c5d950c1 100644
--- a/docs/narr/traversal.rst
+++ b/docs/narr/traversal.rst
@@ -3,6 +3,13 @@
 Traversal
 =========
 
+This chapter explains the technical details of how traversal works in
+Pyramid.
+
+For a quick example, see :doc:`hellotraversal`.
+
+For more about *why* you might use traversal, see :doc:`muchadoabouttraversal`.
+
 A :term:`traversal` uses the URL (Universal Resource Locator) to find a
 :term:`resource` located in a :term:`resource tree`, which is a set of
 nested dictionary-like objects.  Traversal is done by using each segment
-- 
cgit v1.2.3