From 7ad0c19622c96fa6d741108da330fb9fb7db49f4 Mon Sep 17 00:00:00 2001 From: Jonathan LaCour Date: Wed, 29 Jun 2011 16:53:05 -0400 Subject: [PATCH] Better routing docs. --- docs/source/routing.rst | 88 ++++++++++++++++++++++++++++++----------- 1 file changed, 65 insertions(+), 23 deletions(-) diff --git a/docs/source/routing.rst b/docs/source/routing.rst index 2023a17..11432bd 100644 --- a/docs/source/routing.rst +++ b/docs/source/routing.rst @@ -3,9 +3,6 @@ Routing ======= -.. note:: - This portion of the documentation is still a work in progress. - When a user requests a Pecan-powered page how does Pecan know which controller to use? Pecan uses a method known as Object-dispatch to map a HTTP request to a controller. Obejct-dispatch begins by splitting the @@ -54,11 +51,31 @@ example above, you may have noticed the ``expose`` decorator. Routing Algorithm ----------------- +Sometimes, the standard object-dispatch routing isn't adquate to properly +route a URL to a controller. Pecan provides several ways to short-circuit +the object-dispatch system to process URLs with more control, including the +``_lookup``, ``_default``, and ``_route`` special methods. Defining these +methods on your controller objects provide several additional ways to +process all or part of a URL. ``_lookup`` ----------- +The ``_lookup`` special method provides a way to process part of a URL, +and then return a new controller object to route on for the remainder. + +A ``_lookup`` method will accept one or more arguments representing chunks +of the URL to be processed, split on `/`, and then a `*remainder` list which +will be processed by the returned controller via object-dispatch. + +The ``_lookup`` method must return a two-tuple including the controller to +process the remainder of the URL, and the remainder of the URL itself. + +The ``_lookup`` method on a controller is called when no other controller +matches the URL via standard object-dispatch. + + Example :: @@ -86,6 +103,10 @@ Example ``_default`` ------------ +The ``_default`` controller is called when no other controller methods +match the URL vis standard object-dispatch. + + Example :: @@ -109,15 +130,20 @@ Example Overriding ``_route`` --------------------- -Example - -:: - - from pecan import expose +The ``_route`` method allows a controller to completely override the routing +mechanism of Pecan. Pecan itself uses the ``_route`` method to implement its +``RestController``. If you want to design an alternative routing system on +top of Pecan, defining a base controller class that defines a ``_route`` method +will enable you to have total control. -Controller Args ---------------- +Controller Arguments +-------------------- + +A controller can receive arguments in a variety of ways, including ``GET`` and +``POST`` variables, and even chunks of the URL itself. ``GET`` and ``POST`` +arguments simply map to arguments on the controller method, while unprocessed +chunks of the URL can be passed as positional arguments to the controller method. Example @@ -131,7 +157,11 @@ Example return msg -Client requests ``/say/hi`` the controller returns "hi". +In this example, if a ``GET`` request is sent to ``/say/hello``, the controller +returns "hello". On the other hand, if a ``GET`` request is sent to +``/say?msg=World``, then the controller returns "World". + +Keyword arguments are also supported for defaults. kwargs @@ -141,18 +171,26 @@ kwargs class RootController(object): @expose() - def say(self, msg=None): - if msg is None: - return "I not sure what to say" - else: - return msg + def say(self, msg="No message"): + return msg + +In this example, if the client requests ``/say?msg=hello`` the controller returns +"hello". However, if the client requests ``/say`` without any arguments, the +controller returns "No message". -Client requests ``/say?msg=hello`` the controller returns "hello". Generic Functions ----------------- -Example +Pecan also provides a unique and useful way to dispatch from a controller to other +methods based upon the ``HTTP`` method (``GET``, ``POST``, ``PUT``, etc.) using +a system called "generic functions." A controller can be flagged as generic via a +keyword argument on the ``@expose`` decorator. This makes it possible to utilize +the ``@when`` decorator on the controller itself to define controllers to be called +instead when certain ``HTTP`` methods are sent. + + +Example :: @@ -161,22 +199,24 @@ Example class RootController(object): @expose(generic=True) def index(self): - pass + return 'Default case' @index.when(method='POST') def index_post(self): - pass + return 'You POSTed to me!' @index.when(method='GET') def index_get(self): - pass + return 'You GET me!' Helper Functions ---------------- -redirect -abort +Pecan also provides several useful helper functions. The ``redirect`` +function allows you to issue internal or ``HTTP 302`` The ``redirect`` +utility, along with several other useful helpers, are documented in +the :ref:`pecan_core`. ``@expose`` @@ -218,3 +258,5 @@ requests ``/hello.json``. The second tells the templating engine to use tells Pecan to use the html_template.mako when the client requests ``/hello.html``. If the client requests ``/hello``, Pecan will use the text/html template. + +Please see :ref:`pecan_decorators` for more information on ``@expose``.