tg.controllers – Controllers

Basic controller classes for turbogears

DecoratedController allows the decorators in tg.decorators to work

ObjectDispatchController is a specialised form of DecoratedController that converts URL portions into traversing Python objects. This controller is usable in plain pylons if you route to it’s “routes_placeholder” method

TGController is a specialised form of ObjectDispatchController that forms the basis of standard TurboGears controllers. The “Root” controller of a standard tg project must be a TGController.

Core Contents

In general, the TG2 users should setup their Root object as a TGController. That plus the redirect function, and the special url function for constructing URL’s constitutes the main functionality of the Controllers. The ObjectDispatchController, and DecoratedController provide controllers that can be used as endpoints for users who are using Routes – either in addition to object dispatch, or as an alternative.

class tg.controllers.TGController

An ObjectDispatchController-derived class for stock-standard TurboGears controllers.

This controller can be used as a baseclass for anything in the object dispatch tree, but it MUST be used in the Root controller and any controller which you intend to do object dispatch from using Routes.

tg.controllers.redirect(*args, **kwargs)

Generate an HTTP redirect.

The function raises an exception internally, which is handled by the framework. The URL may be either absolute (e.g. http://example.com or /myfile.html) or relative. Relative URLs are automatically converted to absolute URLs. Parameters may be specified, which are appended to the URL. This causes an external redirect via the browser; if the request is POST, the browser will issue GET for the second request.

tg.controllers.url(*args, **kwargs)

Generate an absolute URL that’s specific to this application.

The URL function takes a string, appends the SCRIPT_NAME and adds url parameters for all of the other keyword arguments passed in.

For backwards compatability you can also pass in a params dictionary which is turned into url params.

In general tg.url is just a proxy for pylons.url which is in turn a proxy for routes url_for function. But if tg1 like params are passed in we support a params dictionary in additon to the standard keyword arguments.

Other Classes

class tg.controllers.DecoratedController

DecoratedController takes action on the decorated controller methods created by the decorators in tg.decorators.

The decorators in tg.decorators create an attribute named ‘decoration’ on the controller method, creating rules as to:

1. how to validate the request,

2. how to render the response,

3. allowing hooks to be registered to happen:

   1. before validation
   2. before the controller method is called
   3. before the rendering takes place, and
   4. after the rendering has happened.

class tg.controllers.ObjectDispatchController

Object dispatch (also “object publishing”) means that each portion of the URL becomes a lookup on an object. The next part of the URL applies to the next object, until you run out of URL. Processing starts on a “Root” object.

Thus, /foo/bar/baz become URL portion “foo”, “bar”, and “baz”. The dispatch looks for the “foo” attribute on the Root URL, which returns another object. The “bar” attribute is looked for on the new object, which returns another object. The “baz” attribute is similarly looked for on this object.

Dispatch does not have to be directly on attribute lookup, objects can also have other methods to explain how to dispatch from them. The search ends when a decorated controller method is found.

The rules work as follows:

1. If the current object under consideration is a decorated controller method, the search is ended.
2. If the current object under consideration has a “default” method, keep a record of that method. If we fail in our search, and the most recent method recorded is a “default” method, then the search is ended with that method returned.
3. If the current object under consideration has a “lookup” method, keep a record of that method. If we fail in our search, and the most recent method recorded is a “lookup” method, then execute the “lookup” method, and start the search again on the return value of that method.
4. If the URL portion exists as an attribute on the object in question, start searching again on that attribute.
5. If we fail our search, try the most recent recorded methods as per 2 and 3.