tg.controllers – Controllers

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

Bases: tg.controllers.decoratedcontroller.DecoratedController, tg.controllers.dispatcher.CoreDispatcher, crank.objectdispatcher.ObjectDispatcher

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.

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.

class tg.controllers.RestController

Bases: tg.controllers.decoratedcontroller.DecoratedController, tg.controllers.dispatcher.CoreDispatcher, crank.restdispatcher.RestDispatcher

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.

Useful Methods

tg.controllers.redirect(base_url='/', params=None, redirect_with=<class 'tg.exceptions.HTTPFound'>, scheme=None)

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(base_url='/', params=None, qualified=False, scheme=None)

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

The URL function takes a string (base_url) and, appends the SCRIPT_NAME and adds parameters for all of the parameters passed into the params dict.

scheme can be passed in case of a qualified url to create an url with the given scheme.

tg.controllers.lurl(base_url=None, params=None, **kwargs)

Like tg.url but is lazily evaluated.

This is useful when creating global variables as no request is in place.

As without a request it wouldn’t be possible to correctly calculate the url using the SCRIPT_NAME this demands the url resolution to when it is displayed for the first time.

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

Bases: tg._compat.NewBase

Decorated controller object.

Creates an interface to hang decoration attributes on controller methods for the purpose of rendering web content.

class tg.controllers.WSGIAppController(app, allow_only=None)

Bases: tg.controllers.tgcontroller.TGController

A controller you can use to mount a WSGI app.