CherryPy makes defining what happens for a given URL quite easy: you just give your Python objects the methods you need. In your templates and your code, you can just use the URLs based on how you’ve defined them for CherryPy.
Sometimes, however, the URLs you use are affected by the environment they’re
in. For example, if your whole TurboGears site is running at
http://yoursite.com/~yourusername/tg, you’ll need to be sure that absolute
URLs take that into account.
TurboGears provides a convenient url function to create these URLs. Let’s say
you want to redirect to
/view?id=5&page=10. You can call
turbogears.url("/view", id=5, page=10) to get a URL that takes into account
the top of the site. How does it know where the top of the site is? The
server.webpath configuration variable will tell it where the top of your
The url function is also available in templates as
Future versions of TurboGears will also make it easy to wire up multiple
TurboGears applications in one site. The
url function already understands
the concept of an application root and will generate absolute URLs relative to
the application root.
Note: in order for the
url function to recognize the application root,
your root controller class must extend from
turbogears.controllers.RootController. It is also recommended that your
controllers extend from
When you reference other parts of your application in the template output by URLs, you should normally use relocatable URLs, i.e. URLs which do not specify a URL scheme and host name, so that they will automatically point to the same server as the page where they are used.
Sometimes, however, you need to construct full, absolute URLs, including the URL scheme
and the server name, so you can include them in e.g. an RSS/Atom feed, an email, a log
file, etc. That is what the
absolute_url function is for. It wraps the normal
url function and takes the same arguments, but always returns a full, absolute URL.
It tries to account for differnt deployment situations, where your TurboGears server
may server differnt virtaul hosts or runs behind a reverse proxy, by using the
X-Forwarded-Host headers when appropriate.
The host name part of the URL, to be more precisely, is determined this way:
tg.url_domainis set and non-null, use this value.
base_url_filter.use_x_forwarded_hostconfig setting is True, use the value from the
base_url_filter.base_urlis non-null, use its value for the host and scheme part of the URL.
server.socket_portconfig settings (defaults to
'localhost:8080'). This should only happen, when the client uses an outdated HTTP version.
The URL scheme (
'https') used is determined in the following way:
base_url_filter.base_urlis used, use the scheme from this URL.
X-Use-SSLrequest header, use
tg.url_schemeis set and non-null, use its value.
# 'tg.url_domain' is set to 'www.server.com' absolute_url('/foo') --> 'http://www.server.com/foo' # Client sends 'Host' header with value 'blog.foo.org' absolute_url('/', article=10) --> 'http://blog.foo.org/?article=10' # 'base_url_filter.on' == True, 'base_url_filter.use_x_forwarded_host' == False # and 'base_url_filter.base_url' == 'http://acme.com:8888/' absolute_url('/about') --> 'http://acme.com:8888/about' # Reverse proxy sets 'X-Use-SSL' header and client sends 'Host' header with value # 'www.secure.org' absolute_url('/login') --> 'https://www.secure.org/login') # 'tg.url_scheme' is set to 'https' and client sends 'Host' header with value # 'www.secure.org' absolute_url('/login') --> 'https://www.secure.org/login')