TurboGears – Hooks

There are three ways in TurboGears to plug behaviors inside the existing applications.

• Hook − It is a mechanism by which it is possible to define an event, and notify registered listeners as and when the events are emitted.
  
• Controller Wrapper − It sits between TurboGears and Controller, so that it is possible to extend controller like a decorator. Thus, it can be attached to any third-party controller application.
• Application Wrapper − It is similar to any WSGI middleware, but works in TurboGears context only.

Here in this chapter, we will discuss how to use hooks inside an existing application.

Hooks

Hooks are events registered in the application’s configuration file app_cfg.py. Any controller is then hooked to these events by event decorators.
The following hooks are defined in TurboGears −

S.No.	Hooks & Description
1	Startup() application wide only, called when the application starts.
2	shutdown() application wide only, called when the application exits.
3	configure_new_app new application got created by the application configurator.
4	before_config(app) application wide only, called right after creating application, but before setting up options and middleware
5	after_config(app) application wide only, called after finishing setting everything up.
6	before_validate Called before performing validation
7	before_call Called after validation, before calling the actual controller method.
8	before_render Called before rendering a controller template, output is the controller return value.
9	after_render Called after finishing rendering a controller template.

Register a Hook

In order to register a Hook, create functions in app_cfg.py and then register them using the following code −

tg.hooks.register(hookane, function, controller)

In the following code, on_startup, on_shutdown and before_render hooks are registered in app_cfg.py.

def on_startup():
   print 'hello, startup world'
   
def on_shutdown():
   print 'hello, shutdown world'
   
def before_render(remainder, params, output):
   print 'system wide before render'
   
# ... (base_config init code)
tg.hooks.register('startup', on_startup)
tg.hooks.register('shutdown', on_shutdown)
tg.hooks.register('before_render', before_render)

The before_render hook is registered with a controller function in the Rootcontroller. Add the following code in controllers\root.py.

from tg.decorators import before_render

class RootController(BaseController):
   @expose('hello.templates.index')
   @before_render(before_render_cb)
 
   def index(self, *args, **kw):
      return dict(page = 'index')

When the application is served, start up message is displayed in the console.

hello, startup world
Starting Standard HTTP server on http://127.0.0.1:8080

When ‘/’ URL is entered in the browser, a message corresponding to the before_render hook is displayed on the console.

system wide before render
Going to render {'page': 'index'}

---