/usr/share/doc/python-nevow/howto/traversal.html

<?xml version="1.0" encoding="utf-8"?><!DOCTYPE html  PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN'  'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'><html lang="en" xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>
      Nevow:
    
      Object Traversal
    </title>
    <link href="stylesheet.css" rel="stylesheet" type="text/css"/>
  </head>

  <body bgcolor="white">
    <h1 class="title">
      Object Traversal
    </h1>
    <div class="toc"><ol><li><a href="#auto0">Object Traversal Basics</a></li><li><a href="#auto1">locateChild In Depth</a></li><li><a href="#auto2">childFactory Method</a></li><li><a href="#auto3">child_* methods and attributes</a></li><li><a href="#auto4">Dots in child names</a></li><li><a href="#auto5">children dictionary</a></li><li><a href="#auto6">The default trailing slash handler</a></li><li><a href="#auto7">ICurrentSegments and IRemainingSegments</a></li><li><a href="#auto8">Conclusion</a></li></ol></div>
    <div class="content">
    <span/>

    <p>
      <strong>Object traversal</strong> 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.
    </p>

    <h2>Object Traversal Basics<a name="auto0"/></h2>

    <p>
      The <strong>root resource</strong> is the top-level object in the URL
      space; it conceptually represents the URI <code>/</code>. The Nevow
      <strong>object traversal</strong> and <strong>object publishing</strong>
      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 <code class="API"><a href="nevow.inevow.IResource" title="nevow.inevow.IResource">nevow.inevow.IResource</a></code>:
    </p>

    <pre class="python"><p class="py-linenumber">1
2
3
4
5
6
7
8
9
</p><span class="py-src-keyword">class</span> <span class="py-src-identifier">IResource</span>(<span class="py-src-parameter">Interface</span>):
    <span class="py-src-keyword">def</span> <span class="py-src-identifier">locateChild</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">ctx</span>, <span class="py-src-parameter">segments</span>):
        <span class="py-src-string">&quot;&quot;&quot;Locate another object which can be adapted to IResource
        Return a tuple of resource, path segments
        &quot;&quot;&quot;</span>

    <span class="py-src-keyword">def</span> <span class="py-src-identifier">renderHTTP</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">ctx</span>):
        <span class="py-src-string">&quot;&quot;&quot;Render a request
        &quot;&quot;&quot;</span>
</pre>

    <p>
      <code class="API"><a href="nevow.inevow.IResource.renderHTTP" title="nevow.inevow.IResource.renderHTTP">renderHTTP</a></code> 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:
    </p>

    <pre class="python"><p class="py-linenumber"> 1
 2
 3
 4
 5
 6
 7
 8
 9
10
</p><span class="py-src-keyword">from</span> <span class="py-src-variable">zope</span>.<span class="py-src-variable">interface</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">implements</span>

<span class="py-src-keyword">class</span> <span class="py-src-identifier">SimpleRoot</span>(<span class="py-src-parameter">object</span>):
    <span class="py-src-variable">implements</span>(<span class="py-src-variable">inevow</span>.<span class="py-src-variable">IResource</span>)

    <span class="py-src-keyword">def</span> <span class="py-src-identifier">locateChild</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">ctx</span>, <span class="py-src-parameter">segments</span>):
        <span class="py-src-keyword">return</span> <span class="py-src-variable">self</span>, ()

    <span class="py-src-keyword">def</span> <span class="py-src-identifier">renderHTTP</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">ctx</span>):
        <span class="py-src-keyword">return</span> <span class="py-src-string">&quot;Hello, world!&quot;</span>
</pre>

    <p>
      This resource, when passed as the root resource to <code class="API"><a href="nevow.appserver.NevowSite" title="nevow.appserver.NevowSite">appserver.NevowSite</a></code> or <code class="API"><a href="nevow.wsgi.createWSGIApplication" title="nevow.wsgi.createWSGIApplication">wsgi.createWSGIApplication</a></code>, 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
      <code>&quot;Hello, world!&quot;</code> will be rendered. Let's examine the value of
      <code>segments</code> for various values of URI:
    </p>

    <ul>
      <li><code>/</code> - <code>('',)</code></li>
      <li><code>/foo/bar</code> - <code>('foo', 'bar')</code></li>
      <li>
        <code>/foo/bar/baz.html</code> -
        <code>('foo', 'bar', 'baz.html')</code>
      </li>
      <li>
        <code>/foo/bar/directory/</code> -
        <code>('foo', 'bar', 'directory', '')</code>
      </li>
    </ul>

    <p>
      So we see that Nevow does nothing more than split the URI on the string
      <code>/</code> 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.
    </p>

    <h2><code>locateChild</code> In Depth<a name="auto1"/></h2>

    <p>
      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:
    </p>

    <pre class="python"><p class="py-linenumber"> 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
</p><span class="py-src-keyword">from</span> <span class="py-src-variable">zope</span>.<span class="py-src-variable">interface</span> <span class="py-src-keyword">import</span> <span class="py-src-variable">implements</span>

<span class="py-src-keyword">class</span> <span class="py-src-identifier">Directory</span>(<span class="py-src-parameter">object</span>):
    <span class="py-src-variable">implements</span>(<span class="py-src-variable">inevow</span>.<span class="py-src-variable">IResource</span>)

    <span class="py-src-keyword">def</span> <span class="py-src-identifier">__init__</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">directory</span>):
        <span class="py-src-variable">self</span>.<span class="py-src-variable">directory</span> = <span class="py-src-variable">directory</span>

    <span class="py-src-keyword">def</span> <span class="py-src-identifier">renderHTTP</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">ctx</span>):
        <span class="py-src-variable">html</span> = [<span class="py-src-string">'&lt;ul&gt;'</span>]
        <span class="py-src-keyword">for</span> <span class="py-src-variable">child</span> <span class="py-src-keyword">in</span> <span class="py-src-variable">os</span>.<span class="py-src-variable">listdir</span>(<span class="py-src-variable">self</span>.<span class="py-src-variable">directory</span>):
            <span class="py-src-variable">fullpath</span> = <span class="py-src-variable">os</span>.<span class="py-src-variable">path</span>.<span class="py-src-variable">join</span>(<span class="py-src-variable">self</span>.<span class="py-src-variable">directory</span>, <span class="py-src-variable">child</span>)
            <span class="py-src-keyword">if</span> <span class="py-src-variable">os</span>.<span class="py-src-variable">path</span>.<span class="py-src-variable">isdir</span>(<span class="py-src-variable">fullpath</span>):
                <span class="py-src-variable">child</span> += <span class="py-src-string">'/'</span>
            <span class="py-src-variable">html</span>.<span class="py-src-variable">extend</span>([<span class="py-src-string">'&lt;li&gt;&lt;a href=&quot;'</span>, <span class="py-src-variable">child</span>, <span class="py-src-string">'&quot;&gt;'</span>, <span class="py-src-variable">child</span>, <span class="py-src-string">'&lt;/a&gt;&lt;/li&gt;'</span>])
        <span class="py-src-variable">html</span>.<span class="py-src-variable">append</span>(<span class="py-src-string">'&lt;/ul&gt;'</span>)
        <span class="py-src-keyword">return</span> <span class="py-src-string">''</span>.<span class="py-src-variable">join</span>(<span class="py-src-variable">html</span>)

    <span class="py-src-keyword">def</span> <span class="py-src-identifier">locateChild</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">ctx</span>, <span class="py-src-parameter">segments</span>):
        <span class="py-src-variable">name</span> = <span class="py-src-variable">segments</span>[<span class="py-src-number">0</span>]
        <span class="py-src-variable">fullpath</span> = <span class="py-src-variable">os</span>.<span class="py-src-variable">path</span>.<span class="py-src-variable">join</span>(<span class="py-src-variable">self</span>.<span class="py-src-variable">directory</span>, <span class="py-src-variable">name</span>)
        <span class="py-src-keyword">if</span> <span class="py-src-keyword">not</span> <span class="py-src-variable">os</span>.<span class="py-src-variable">path</span>.<span class="py-src-variable">exists</span>(<span class="py-src-variable">fullpath</span>):
            <span class="py-src-keyword">return</span> <span class="py-src-variable">None</span>, () <span class="py-src-comment"># 404</span>

        <span class="py-src-keyword">if</span> <span class="py-src-variable">os</span>.<span class="py-src-variable">path</span>.<span class="py-src-variable">isdir</span>(<span class="py-src-variable">fullpath</span>):
            <span class="py-src-keyword">return</span> <span class="py-src-variable">Directory</span>(<span class="py-src-variable">fullpath</span>), <span class="py-src-variable">segments</span>[<span class="py-src-number">1</span>:]
        <span class="py-src-keyword">if</span> <span class="py-src-variable">os</span>.<span class="py-src-variable">path</span>.<span class="py-src-variable">isfile</span>(<span class="py-src-variable">fullpath</span>):
            <span class="py-src-keyword">return</span> <span class="py-src-variable">static</span>.<span class="py-src-variable">File</span>(<span class="py-src-variable">fullpath</span>), <span class="py-src-variable">segments</span>[<span class="py-src-number">1</span>:]
</pre>

    <p>
      Because this implementation of <code>locateChild</code> only consumed one
      segment and returned the rest of them (<code>segments[1:]</code>), the
      object traversal process will continue by calling
      <code>locateChild</code> on the returned resource and passing the
      partially-consumed segments. In this way, a directory structure of any
      depth can be traversed, and directory listings or file contents can be
      rendered for any existing directories and files.
    </p>

    <p>
      So, let us examine what happens when the URI
      <code>&quot;/foo/bar/baz.html&quot;</code> is traversed, where <code>&quot;foo&quot;</code>
      and <code>&quot;bar&quot;</code> are directories, and <code>&quot;baz.html&quot;</code> is a
      file.
    </p>

    <ol>
      <li>
        <code>
          Directory('/').locateChild(ctx, ('foo', 'bar', 'baz.html'))
        </code>
        returns
        <code>Directory('/foo'), ('bar', 'baz.html')</code>
      </li>
      <li>
        <code>
          Directory('/foo').locateChild(ctx, ('bar', 'baz.html'))
        </code>
        returns
        <code>Directory('/foo/bar'), ('baz.html, )</code>
      </li>
      <li>
        <code>
          Directory('/foo/bar').locateChild(ctx, ('baz.html'))
        </code>
        returns
        <code>File('/foo/bar/baz.html'), ()</code>
      </li>
      <li>
        No more segments to be consumed;
        <code>File('/foo/bar/baz.html').renderHTTP(ctx)</code> is called, and
        the result is sent to the browser.
      </li>
    </ol>


    <h2><code>childFactory</code> Method<a name="auto2"/></h2>

    <p>
      Consuming one URI segment at a time by checking to see if a requested
      resource exists and returning a new object is a very common
      pattern. Nevow's default implementation of <code class="API"><a href="nevow.inevow.IResource" title="nevow.inevow.IResource">IResource</a></code>, <code class="API"><a href="nevow.rend.Page" title="nevow.rend.Page">nevow.rend.Page</a></code>, contains an implementation of
      <code>locateChild</code> which provides more convenient hooks for
      implementing object traversal. One of these hooks is
      <code>childFactory</code>. Let us imagine for the sake of example that we
      wished to render a tree of dictionaries. Our data structure might look
      something like this:
    </p>

    <pre class="python"><p class="py-linenumber">1
2
3
4
5
6
7
</p><span class="py-src-variable">tree</span> = <span class="py-src-variable">dict</span>(
    <span class="py-src-variable">one</span>=<span class="py-src-variable">dict</span>(
        <span class="py-src-variable">foo</span>=<span class="py-src-variable">None</span>,
        <span class="py-src-variable">bar</span>=<span class="py-src-variable">None</span>),
    <span class="py-src-variable">two</span>=<span class="py-src-variable">dict</span>(
        <span class="py-src-variable">baz</span>=<span class="py-src-variable">dict</span>(
        <span class="py-src-variable">quux</span>=<span class="py-src-variable">None</span>)))
</pre>

    <p>
      Given this data structure, the valid URIs would be:
    </p>

    <ul>
      <li>/</li>
      <li>/one</li>
      <li>/one/foo</li>
      <li>/one/bar</li>
      <li>/two</li>
      <li>/two/baz</li>
      <li>/two/baz/quux</li>
    </ul>

    <p>
      Let us construct a <code class="API"><a href="nevow.rend.Page" title="nevow.rend.Page">rend.Page</a></code>
      subclass which uses the default <code>locateChild</code> implementation
      and overrides the <code>childFactory</code> hook instead:
    </p>

    <pre class="python"><p class="py-linenumber"> 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
</p><span class="py-src-keyword">class</span> <span class="py-src-identifier">DictTree</span>(<span class="py-src-parameter">rend</span>.<span class="py-src-parameter">Page</span>):
    <span class="py-src-keyword">def</span> <span class="py-src-identifier">__init__</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">dataDict</span>):
        <span class="py-src-variable">self</span>.<span class="py-src-variable">dataDict</span> = <span class="py-src-variable">dataDict</span>

    <span class="py-src-keyword">def</span> <span class="py-src-identifier">renderHTTP</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">ctx</span>):
        <span class="py-src-keyword">if</span> <span class="py-src-variable">self</span>.<span class="py-src-variable">dataDict</span> <span class="py-src-keyword">is</span> <span class="py-src-variable">None</span>:
            <span class="py-src-keyword">return</span> <span class="py-src-string">&quot;Leaf&quot;</span>
        <span class="py-src-variable">html</span> = [<span class="py-src-string">'&lt;ul&gt;'</span>]
        <span class="py-src-keyword">for</span> <span class="py-src-variable">key</span> <span class="py-src-keyword">in</span> <span class="py-src-variable">self</span>.<span class="py-src-variable">dataDict</span>.<span class="py-src-variable">keys</span>():
            <span class="py-src-variable">html</span>.<span class="py-src-variable">extend</span>([<span class="py-src-string">'&lt;li&gt;&lt;a href=&quot;'</span>, <span class="py-src-variable">key</span>, <span class="py-src-string">'&quot;&gt;'</span>, <span class="py-src-variable">key</span>, <span class="py-src-string">'&lt;/a&gt;&lt;/li&gt;'</span>])
        <span class="py-src-variable">html</span>.<span class="py-src-variable">append</span>(<span class="py-src-string">'&lt;/ul&gt;'</span>)
        <span class="py-src-keyword">return</span> <span class="py-src-string">''</span>.<span class="py-src-variable">join</span>(<span class="py-src-variable">html</span>)

    <span class="py-src-keyword">def</span> <span class="py-src-identifier">childFactory</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">ctx</span>, <span class="py-src-parameter">name</span>):
        <span class="py-src-keyword">if</span> <span class="py-src-variable">name</span> <span class="py-src-keyword">not</span> <span class="py-src-keyword">in</span> <span class="py-src-variable">self</span>.<span class="py-src-variable">dataDict</span>:
            <span class="py-src-keyword">return</span> <span class="py-src-variable">rend</span>.<span class="py-src-variable">NotFound</span> <span class="py-src-comment"># 404</span>
        <span class="py-src-keyword">return</span> <span class="py-src-variable">DictTree</span>(<span class="py-src-variable">self</span>.<span class="py-src-variable">dataDict</span>[<span class="py-src-variable">name</span>])
</pre>

    <p>
      As you can see, the <code>childFactory</code> implementation is
      considerably shorter than the equivalent <code>locateChild</code>
      implementation would have been.
    </p>

    <h2><code>child_*</code> methods and attributes<a name="auto3"/></h2>

    <p>
      Often we may wish to have some hardcoded URLs which are not dynamically
      generated based on some data structure. For example, we might have an
      application which uses an external CSS stylesheet, an external JavaScript
      file, and a folder full of images. The <code class="API"><a href="nevow.rend.Page.locateChild" title="nevow.rend.Page.locateChild">rend.Page.locateChild</a></code> implementation provides a
      convenient way for us to express these relationships by using
      child-prefixed methods:
    </p>

    <pre class="python"><p class="py-linenumber"> 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
</p><span class="py-src-keyword">class</span> <span class="py-src-identifier">Linker</span>(<span class="py-src-parameter">rend</span>.<span class="py-src-parameter">Page</span>):
    <span class="py-src-keyword">def</span> <span class="py-src-identifier">renderHTTP</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">ctx</span>):
        <span class="py-src-keyword">return</span> <span class="py-src-string">&quot;&quot;&quot;&lt;html&gt;
&lt;head&gt;
    &lt;link href=&quot;css&quot; rel=&quot;stylesheet&quot; /&gt;
    &lt;script type=&quot;text/javascript&quot; src=&quot;scripts&quot; /&gt;
  &lt;body&gt;
    &lt;img src=&quot;images/logo.png&quot; /&gt;
  &lt;/body&gt;
&lt;/html&gt;&quot;&quot;&quot;</span>

    <span class="py-src-keyword">def</span> <span class="py-src-identifier">child_css</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">ctx</span>):
        <span class="py-src-keyword">return</span> <span class="py-src-variable">static</span>.<span class="py-src-variable">File</span>(<span class="py-src-string">'styles.css'</span>)

    <span class="py-src-keyword">def</span> <span class="py-src-identifier">child_scripts</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">ctx</span>):
        <span class="py-src-keyword">return</span> <span class="py-src-variable">static</span>.<span class="py-src-variable">File</span>(<span class="py-src-string">'scripts.js'</span>)

    <span class="py-src-keyword">def</span> <span class="py-src-identifier">child_images</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">ctx</span>):
        <span class="py-src-keyword">return</span> <span class="py-src-variable">static</span>.<span class="py-src-variable">File</span>(<span class="py-src-string">'images/'</span>)
</pre>

    <p>
      One thing you may have noticed is that all of the examples so far have
      returned new object instances whenever they were implementing a traversal
      API. However, there is no reason these instances cannot be shared. One
      could for example return a global resource instance, an instance which
      was previously inserted in a dict, or lazily create and cache dynamic
      resource instances on the fly. The <code>rend.Page.locateChild</code>
      implementation also provides a convenient way to express that one global
      resource instance should always be used for a particular URL, the
      child-prefixed attribute:
    </p>

    <pre class="python"><p class="py-linenumber">1
2
3
4
</p><span class="py-src-keyword">class</span> <span class="py-src-identifier">FasterLinker</span>(<span class="py-src-parameter">Linker</span>):
    <span class="py-src-variable">child_css</span> = <span class="py-src-variable">static</span>.<span class="py-src-variable">File</span>(<span class="py-src-string">'styles.css'</span>)
    <span class="py-src-variable">child_scripts</span> = <span class="py-src-variable">static</span>.<span class="py-src-variable">File</span>(<span class="py-src-string">'scripts.js'</span>)
    <span class="py-src-variable">child_images</span> = <span class="py-src-variable">static</span>.<span class="py-src-variable">File</span>(<span class="py-src-string">'images/'</span>)
</pre>

    <h2>Dots in child names<a name="auto4"/></h2>

    <p>
      When a URL contains dots, which is quite common in normal URLs, it is
      simple enough to handle these URL segments in <code>locateChild</code> or
      <code>childFactory</code> -- one of the passed segments will simply be a
      string containing a dot. However, it is not immediately obvious how one
      would express a URL segment with a dot in it when using child-prefixed
      methods. The solution is really quite simple:
    </p>

    <pre class="python"><p class="py-linenumber"> 1
 2
 3
 4
 5
 6
 7
 8
 9
10
</p><span class="py-src-keyword">class</span> <span class="py-src-identifier">DotChildren</span>(<span class="py-src-parameter">rend</span>.<span class="py-src-parameter">Page</span>):
    <span class="py-src-keyword">def</span> <span class="py-src-identifier">renderHTTP</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">ctx</span>):
        <span class="py-src-keyword">return</span> <span class="py-src-string">&quot;&quot;&quot;
        &lt;html&gt;
          &lt;head&gt;
            &lt;script type=&quot;text/javascript&quot; src=&quot;scripts.js&quot; /&gt;
          &lt;/head&gt;
        &lt;/html&gt;&quot;&quot;&quot;</span>

<span class="py-src-variable">setattr</span>(<span class="py-src-variable">DotChildren</span>, <span class="py-src-string">'child_scripts.js'</span>, <span class="py-src-variable">static</span>.<span class="py-src-variable">File</span>(<span class="py-src-string">'scripts.js'</span>))
</pre>

    <p>
      The same technique could be used to install a child method with a dot in
      the name.
    </p>


    <h2>children dictionary<a name="auto5"/></h2>

    <p>
      The final hook supported by the default implementation of
      <code>locateChild</code> is the <code>rend.Page.children</code>
      dictionary:
    </p>

    <pre class="python"><p class="py-linenumber"> 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
</p><span class="py-src-keyword">class</span> <span class="py-src-identifier">Main</span>(<span class="py-src-parameter">rend</span>.<span class="py-src-parameter">Page</span>):
    <span class="py-src-variable">children</span> = {
        <span class="py-src-string">'people'</span>: <span class="py-src-variable">People</span>(),
        <span class="py-src-string">'jobs'</span>: <span class="py-src-variable">Jobs</span>(),
        <span class="py-src-string">'events'</span>: <span class="py-src-variable">Events</span>()}

    <span class="py-src-keyword">def</span> <span class="py-src-identifier">renderHTTP</span>(<span class="py-src-parameter">self</span>, <span class="py-src-parameter">ctx</span>):
        <span class="py-src-keyword">return</span> <span class="py-src-string">&quot;&quot;&quot;
        &lt;html&gt;
          &lt;head&gt;
            &lt;title&gt;Our Site&lt;/title&gt;
          &lt;/head&gt;
          &lt;body&gt;
            &lt;p&gt;bla bla bla&lt;/p&gt;
          &lt;/body&gt;
        &lt;/html&gt;&quot;&quot;&quot;</span>
</pre>

    <p>
      Hooks are checked in the following order:
    </p>

    <ol>
      <li><code>self.children</code></li>
      <li><code>self.child_*</code></li>
      <li><code>self.childFactory</code></li>
    </ol>

    <h2>The default trailing slash handler<a name="auto6"/></h2>

    <p>
      When a URI which is being handled ends in a slash, such as when the
      <code>/</code> URI is being rendered or when a directory-like URI is
      being rendered, the string <code>''</code> appears in the path segments
      which will be traversed. Again, handling this case is trivial inside
      either <code>locateChild</code> or <code>childFactory</code>, 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
      <code>child</code> with a single trailing underscore.
    </p>

    <p>
      The <code>rend.Page</code> class provides an implementation of this
      method which can work in two different ways. If the attribute
      <code>addSlash</code> is <code>True</code>, the default trailing slash
      handler will return <code>self</code>. In the case when
      <code>addSlash</code> is <code>True</code>, the default
      <code>rend.Page.renderHTTP</code> implementation will simply perform a
      redirect which adds the missing slash to the URL.
    </p>

    <p>
      The default trailing slash handler also returns self if
      <code>addSlash</code> is <code>False</code>, but emits a warning as it
      does so. This warning may become an exception at some point in the
      future.
    </p>

    <h2><code>ICurrentSegments</code> and <code>IRemainingSegments</code><a name="auto7"/></h2>

    <p>
      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 <code>context</code>
      object which is passed to all the traversal APIs. The interfaces <code class="API"><a href="nevow.inevow.ICurrentSegments" title="nevow.inevow.ICurrentSegments">nevow.inevow.ICurrentSegments</a></code> and <code class="API"><a href="nevow.inevow.IRemainingSegments" title="nevow.inevow.IRemainingSegments">nevow.inevow.IRemainingSegments</a></code> are used to retrieve
      this information. To retrieve a tuple of segments which have previously
      been consumed during object traversal, use this syntax:
    </p>

    <pre class="python"><p class="py-linenumber">1
</p><span class="py-src-variable">segs</span> = <span class="py-src-variable">ICurrentSegments</span>(<span class="py-src-variable">ctx</span>)
</pre>

    <p>
      The same is true of <code>IRemainingSegments</code>.
      <code>IRemainingSegments</code> is the same value which is passed as
      <code>segments</code> to <code>locateChild</code>, but may also be useful
      in the implementations of <code>childFactory</code> or a child-prefixed
      method, where this information would not otherwise be available.
    </p>

    <h2>Conclusion<a name="auto8"/></h2>

    <p>
      Nevow makes it easy to handle complex URL hierarchies. The most basic
      object traversal interface, <code class="API"><a href="nevow.inevow.IResource.locateChild" title="nevow.inevow.IResource.locateChild">nevow.inevow.IResource.locateChild</a></code>, provides powerful
      and flexible control over the entire object traversal process. Nevow's
      canonical <code>IResource</code> implementation, <code>rend.Page</code>,
      also includes the convenience hooks <code>childFactory</code> along with
      child-prefixed method and attribute semantics to simplify common use
      cases.
    </p>
  </div>

    <p><a href="index.html">Index</a></p>
    <span class="version">Version: </span>
  </body>
</html>
python-nevow 0.10.0-4build1 / usr / share / doc / python-nevow / howto / traversal.html
