root/branches/cherrypy-2.x/docs/book/xml/globaloverviewcherrypy.xml

<?xml version="1.0" encoding="UTF-8"?>
<section xmlns:db="http://docbook.org/docbook-ng" xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xml:id="globaloverviewcherrypy">
    <title>Global Overview</title>
    <section>
        <title>Mapping URI's to handlers</title>
        <para>CherryPy has lots of fancy features to help you manage HTTP messages. But the most
        fundamental thing it does is allow you to map URI's to handler functions. It does this in a
        very straightforward way: the path portion of a URI is heirarchical, so CherryPy uses a
        parallel heirarchy of objects, starting with <code>cherrypy.root</code>. If your application
        receives a request for "/admin/user?name=idunno", then CherryPy will try to find the handler:
        <code>cherrypy.root.admin.user</code>. If it exists, is callable, and has an "exposed = True"
        attribute, then CherryPy will hand off control to that function. Any URI parameters (like
        "name=idunno", above) are passed to the handler as keyword arguments.</para>
        <section>
            <title>Index methods</title>
            <para>There are some special cases, however. To what handler should we map a path like
            "/admin/search/"? Note the trailing slash after "search"—it indicates that our path has
            three components: "admin", "search", and "". Static webservers interpret this to mean
            that the <code>search</code> object is a directory, and, since the third component is
            blank, they use an <code>index.html</code> file if it exists. CherryPy is a dynamic
            webserver, so it allows you to specify an <code>index</code> method to handle this. In
            our example, CherryPy will look for a handler at
            <code>cherrypy.root.admin.search.index</code>. Let's pause and show our example
            application so far:</para>
            <example>
                <title>Sample application (handler mapping example)</title>
                <programlisting>import cherrypy

class Root:
    def index(self):
        return "Hello, world!"
    index.exposed = True

class Admin:
    def user(self, name=""):
        return "You asked for user '%s'" % name
    user.exposed = True

class Search:
    def index(self):
        return search_page()
    index.exposed = True

cherrypy.root = Root()
cherrypy.root.admin = Admin()
cherrypy.root.admin.search = Search()</programlisting>
            </example>
            <para>So far, we have three exposed handlers:</para>
            <itemizedlist>
                <listitem>
                    <para><code>root.index</code>. This will be called for the URI's "/" and
                    "/index".</para>
                </listitem>
                <listitem>
                    <para><code>root.admin.user</code>. This will be called for the URI
                    "/admin/user".</para>
                </listitem>
                <listitem>
                    <para><code>root.admin.search.index</code>. This will be called for the URI's
                    "/admin/search/" and "/admin/search".</para>
                </listitem>
            </itemizedlist>
            <para>Yes, you read that third line correctly: <code>root.admin.search.index</code> will
            be called whether or not the URI has a trailing slash. Actually, that isn't quite true;
            CherryPy will answer a request for "/admin/search" (without the slash) with an HTTP
            Redirect response. Most browsers will then request "/admin/search/" as the redirection
            suggests, and <emphasis>then</emphasis> our <code>root.admin.search.index</code> handler
            will be called. But the final outcome is the same.</para>
        </section>
        <section>
            <title>Positional Parameters</title>
            <para>Now, let's consider another special case. What if, instead of passing a user name
            as a parameter, we wish to use a user id as part of the path? What to do with a URI like
            "/admin/user/8173/schedule"? This is intended to reference the schedule belonging to
            "user #8173", but we certainly don't want to have a separate function for each user
            id!</para>
            <para>CherryPy allows you to map a single handler to multiple URI's with the simple
            approach of <emphasis>not writing handlers you don't need</emphasis>. If a node in the
            <code>cherrypy.root</code> tree doesn't have any children, that node will be called for
            all of its child paths, and CherryPy will pass the leftover path info as positional
            arguments. In our example, CherryPy will call <code>cherrypy.root.admin.user("8173",
            "schedule")</code>. Let's rewrite our user method to handle such requests:</para>
            <example>
                <title>A user method which handles positional parameters</title>
                <programlisting>class Admin:
    def user(self, *args):
        if not args:
            raise cherrypy.HTTPError(400, "A user id was expected but not supplied.")
        id = args.pop(0)
        if args and args[0] == 'schedule':
            return self.schedule(id)
        return "You asked for user '%s'" % id
    user.exposed = True</programlisting>
            </example>
            <para>Note that this is different behavior than CherryPy 2.1, which only allowed
            positional params for methods named "default".</para>
        </section>
        <section>
            <title>Default methods</title>
            <para>Are you ready for another special case? What handler is called in our example if
            you request the URI "/not/a/valid/path"? Given the behavior we have described up to this
            point, you might deduce that the <code>root.index</code> method will end up handling
            <emphasis>any</emphasis> path that can't be mapped elsewhere. This would mean, in effect,
            that CherryPy applications with a <code>root.index</code> could never return a "404 Not
            Found" response!</para>
            <para>To prevent this, CherryPy doesn't try to call index methods unless they are
            attached to the last node in the path; in our example, the only index method that might
            be called would be a <code>root.not.a.valid.path.index</code> method. If you truly want
            an intermediate index method to receive positional parameters, well, you can't do that.
            But what you can do is define a <code>default</code> method to do that for you, instead
            of an <code>index</code> method. If we wanted our <code>cherrypy.root</code> to handle
            any child path, and receive positional parameters, we could rewrite it like this:</para>
            <example>
                <title>A <code>default</code> method example</title>
                <programlisting>class Root:
    def index(self):
        return "Hello, world!"
    index.exposed = True
    
    def default(self, *args):
        return "Extra path info: %s" % repr(args)
    default.exposed = True</programlisting>
            </example>
            <para>This new Root class would handle the URI's "/" and "/index" via the
            <code>index</code> method, and would handle URI's like "/not/a/valid/path" and
            "/admin/unknown" via the <code>default</code> method.</para>
        </section>
        <section>
            <title>Traversal examples</title>
            <para>For those of you who need to see in exactly what order CherryPy will try various
            handlers, here are some examples, using the application above. We always start by trying
            to find the longest object path first, and then working backwards until an exposed,
            callable handler is found:</para>
            <example>
                <title>Traversal examples</title>
                <programlisting>"/admin/user/8192/schedule"
    Trying to reach cherrypy.root.admin.user.8192.schedule.index...
    cherrypy.root                     exists? Yes.
            .root.admin               exists? Yes.
                 .admin.user          exists? Yes.
                       .user.8192     exists? No.
                       .user.default  is callable and exposed? No.
                 .admin.user          is callable and exposed? Yes. Call it.

"/admin/search/"
    Trying to reach cherrypy.root.admin.search.index...
    cherrypy.root                     exists? Yes.
            .root.admin               exists? Yes.
                 .admin.search        exists? Yes.
                       .search.index  exists? Yes. Path exhausted.
                       .search.index  is callable and exposed? Yes. Call it.

"/admin/unknown"
    Trying to reach cherrypy.root.admin.unknown.index...
    cherrypy.root                     exists? Yes.
            .root.admin               exists? Yes.
                 .admin.unknown       exists? No.
                 .admin.default       is callable and exposed? No.
            .root.admin               is callable and exposed? No.
            .root.default             is callable and exposed? Yes. Call it.</programlisting>
            </example>
        </section>
    </section>
</section>