Object Traversal ================ **Object traversal** is the process Nevow uses to determine what object to use to render HTML for a particular URL. When an HTTP request comes in to the web server, the object publisher splits the URL into segments, and repeatedly calls methods which consume path segments and return objects which represent that path, until all segments have been consumed. At the core, the Nevow traversal API is very simple. However, it provides some higher level functionality layered on top of this to satisfy common use cases. Object Traversal Basics ----------------------- The **root resource** is the top-level object in the URL space; it conceptually represents the URI ``/`` . The Nevow **object traversal** and **object publishing** machinery uses only two methods to locate an object suitable for publishing and to generate the HTML from it; these methods are described in the interface ``nevow.inevow.IResource`` : :: class IResource(Interface): def locateChild(self, ctx, segments): """Locate another object which can be adapted to IResource Return a tuple of resource, path segments """ def renderHTTP(self, ctx): """Render a request """ ``renderHTTP`` can be as simple as a method which simply returns a string of HTML. Let's examine what happens when object traversal occurs over a very simple root resource: :: from zope.interface import implements class SimpleRoot(object): implements(inevow.IResource) def locateChild(self, ctx, segments): return self, () def renderHTTP(self, ctx): return "Hello, world!" This resource, when passed as the root resource to ``appserver.NevowSite`` or ``wsgi.createWSGIApplication`` , will immediately return itself, consuming all path segments. This means that for every URI a user visits on a web server which is serving this root resource, the text ``"Hello, world!"`` will be rendered. Let's examine the value of ``segments`` for various values of URI: - ``/`` - ``('',)`` - ``/foo/bar`` - ``('foo', 'bar')`` - ``/foo/bar/baz.html`` - ``('foo', 'bar', 'baz.html')`` - ``/foo/bar/directory/`` - ``('foo', 'bar', 'directory', '')`` So we see that Nevow does nothing more than split the URI on the string ``/`` and pass these path segments to our application for consumption. Armed with these two methods alone, we already have enough information to write applications which service any form of URL imaginable in any way we wish. However, there are some common URL handling patterns which Nevow provides higher level support for. ``locateChild`` In Depth ------------------------- One common URL handling pattern involves parents which only know about their direct children. For example, a ``Directory`` object may only know about the contents of a single directory, but if it contains other directories, it does not know about the contents of them. Let's examine a simple ``Directory`` object which can provide directory listings and serves up objects for child directories and files: :: from zope.interface import implements class Directory(object): implements(inevow.IResource) def __init__(self, directory): self.directory = directory def renderHTTP(self, ctx): html = ['
bla bla bla""" Hooks are checked in the following order: #. ``self.children`` #. ``self.child_*`` #. ``self.childFactory`` The default trailing slash handler ---------------------------------- When a URI which is being handled ends in a slash, such as when the ``/`` URI is being rendered or when a directory-like URI is being rendered, the string ``''`` appears in the path segments which will be traversed. Again, handling this case is trivial inside either ``locateChild`` or ``childFactory`` , but it may not be immediately obvious what child-prefixed method or attribute will be looked up. The method or attribute name which will be used is simply ``child`` with a single trailing underscore. The ``rend.Page`` class provides an implementation of this method which can work in two different ways. If the attribute ``addSlash`` is ``True`` , the default trailing slash handler will return ``self`` . In the case when ``addSlash`` is ``True`` , the default ``rend.Page.renderHTTP`` implementation will simply perform a redirect which adds the missing slash to the URL. The default trailing slash handler also returns self if ``addSlash`` is ``False`` , but emits a warning as it does so. This warning may become an exception at some point in the future. ``ICurrentSegments`` and ``IRemainingSegments`` ------------------------------------------------ During the object traversal process, it may be useful to discover which segments have already been handled and which segments are remaining to be handled. This information may be obtained from the ``context`` object which is passed to all the traversal APIs. The interfaces ``nevow.inevow.ICurrentSegments`` and ``nevow.inevow.IRemainingSegments`` are used to retrieve this information. To retrieve a tuple of segments which have previously been consumed during object traversal, use this syntax: :: segs = ICurrentSegments(ctx) The same is true of ``IRemainingSegments`` . ``IRemainingSegments`` is the same value which is passed as ``segments`` to ``locateChild`` , but may also be useful in the implementations of ``childFactory`` or a child-prefixed method, where this information would not otherwise be available. Conclusion ---------- Nevow makes it easy to handle complex URL hierarchies. The most basic object traversal interface, ``nevow.inevow.IResource.locateChild`` , provides powerful and flexible control over the entire object traversal process. Nevow's canonical ``IResource`` implementation, ``rend.Page`` , also includes the convenience hooks ``childFactory`` along with child-prefixed method and attribute semantics to simplify common use cases.