tg.controllers – Controllers

Controller Classes, dispatch methods and helper functions for controller operation.

This module contains the main classes which describe Turbogears2 Controllers. These Controllers are handled by the Dispatch functions which are also provided here.

Lastly, url definition and browser redirection are defined here.

Common Controller Classes

There are two main methods for defining controllers in a TG2 system. The first method is ObjectDispatch-based, and is similar to the way TG1 dispatch worked. RootControllers should be defined with this class. This will allow the normal nested-style dispatch of URLS as is expected with TG1.

The second controller is RestController, which defines a RESTful interface for URL dispatch. This provides Controller-Specific methods which are unique to dispatch using REST architecture. RestControllers may be inter-twined with “regular” controllers to provide any mix of dispatch the developer desires.

Controller classess along with the redirect function, and the special url function for constructing URL’s constitutes the main functionality of the Controllers part of MVC.

class tg.controllers.TGController(*args, **kwargs)

Bases: tg.controllers.ObjectDispatchController

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

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.

This controller has a few reserved method names which provide special functionality.

Method Description Example URL(s)
index The root of the controller. /
default A method to call when all other methods have failed. /movies
lookup Allows the developer to return a Controller instance for further dispatch. /location/23.35/2343.34/elevation
References:Controller A basic overview on how to write controller methods.
__before__(*args, **kw)
Override this method to define any action you would like taken before the controller code is executed. This is particularly useful for defining a Controller-wide specification (all methods) for things like: setting up variables/objects in the template context, restricting access, or other tasks which should be executed before the controller method is called.
__after__(*args, **kw)

Override this method to define what you would like to run after the template has been rendered. This method will always be run after your method, even if it raises an Exception or redirects.

An example use-case would be a runtime-specific template change, you where would want to change the template back to the originally decorated template after you have temporarily changed it.

class tg.controllers.RestController(*args, **kwargs)

Bases: tg.controllers.DecoratedController

A Decorated Controller that dispatches in a RESTful Manner.

This controller was designed to follow Representational State Transfer protocol, also known as REST. The goal of this controller method is to provide the developer a way to map RESTful URLS to controller methods directly, while still allowing Normal Object Dispatch to occur.

Here is a brief rundown of the methods which are called on dispatch along with an example URL.

Method Description Example Method(s) / URL(s)
get_one Display one record. GET /movies/1
get_all Display all records in a resource. GET /movies/
get A combo of get_one and get_all. GET /movies/
GET /movies/1
new Display a page to prompt the User for resource creation. GET /movies/new
edit Display a page to prompt the User for resource modification. GET /movies/1/edit
post Create a new record. POST /movies/
put Update an existing record. POST /movies/1?_method=PUT
PUT /movies/1
post_delete Delete an existing record. POST /movies/1?_method=DELETE
DELETE /movies/1
get_delete Display a delete Confirmation page. GET /movies/1/delete
delete A combination of post_delete and get_delete. GET /movies/delete
DELETE /movies/1
DELETE /movies/
POST /movies/1/delete
POST /movies/delete

You may note the ?_method on some of the URLs. This is basically a hack because exiting browsers do not support the PUT and DELETE methods. Just note that if you decide to use a this resource with a web browser, you will likely have to add a _method as a hidden field in your forms for these items. Also note that RestController differs from TGController in that it offers no index, default, or lookup. It is intended primarily for resource management.

References:

Controller A basic overview on how to write controller methods.

CrudRestController A way to integrate ToscaWdiget Functionality with RESTful Dispatch.

__before__(*args, **kw)
Override this method to define any action you would like taken before the controller code is executed. This is particularly useful for defining a Controller-wide specification (all methods) for things like: setting up variables/objects in the template context, restricting access, or other tasks which should be executed before the controller method is called.
__after__(*args, **kw)

Override this method to define what you would like to run after the template has been rendered. This method will always be run after your method, even if it raises an Exception or redirects.

An example use-case would be a runtime-specific template change, you where would want to change the template back to the originally decorated template after you have temporarily changed it.

Useful Methods

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 compatibility you can also pass in a params dictionary which is turned into url params, or you can send in a a list of strings as the first argument, which will be joined with /’s to make a url string.

In general tg.url is just a proxy for pylons.url which is in turn a proxy for routes url_for function. This means that if the first argument is not a basestring but a method that has been routed to, the standard routes url_for reverse lookup system will be used.

Other Classes

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.DecoratedController(*args, **kwargs)

Bases: pylons.controllers.core.WSGIController

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(*args, **kwargs)

Bases: tg.controllers.DecoratedController

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.
class tg.controllers.WSGIAppController(app, allow_only=None)

Bases: tg.controllers.TGController

A controller you can use to mount a WSGI app.

Table Of Contents

Previous topic

Mounting WSGI Applications as TG Controllers

Next topic

Using Genshi in TG2

This Page