Changes between Version 6 and Version 7 of UrlRouting

Timestamp:

Jul 9, 2008, 11:55:23 AM (16 years ago)

Author:

cmlenz

Comment:

URL generation

UrlRouting

@@ -26 +26 @@
  * the '''target''' function that should handle requests matching that pattern (optional).
 
-Additional indented lines can be provided to set default values for parameters that get passed on to the request handler. The value of these parameters can be any Python expression.
+Additional indented lines can be provided below any route to set default values for parameters that get passed on to the request handler. The value of these parameters can be any Python expression.
 
 If no name is specified for a route, URLs for that route can not be generated by name, but only based on the function object. If no target is specified, the route is only used for generating links, not for dispatching requests.
+
+== Generating URLs ==
+
+The `diva.routing` modules provides a number of ways to generate URLs based on the routing.
+
+The central function is `path_to(target, *args, **kwargs)`. Here, `target` is either the name of the route, or the function handling the route. Additional arguments are substituted for variables in the path of the route. Any remaining keyword arguments are added as query string parameters:
+
+{{{
+#!pycon
+>>> from diva.routing import path_to
+>>> path_to('info', id=42)
+/info/42
+>>> path_to('info', id=42, page=2)
+/info/42?page=2
+}}}
+
+Use the `abs_url` function to turn such relative URLs into absolute ones including scheme and host:
+
+{{{
+#!pycon
+>>> from diva.routing import abs_url, path_to
+>>> abs_url(path_to('info', id=42))
+http://localhost:8080/info/42
+}}}
+
+Finally, the `redirect(target, *args, **kwargs)` function is a shortcut for redirecting to the absolutized result of `path_to(). It will raise an HTTP exception, and thus immediately break out of the current code.
 
 == API Documentation ==
 
 [[PythonDoc(trunk, diva.routing)]]
+