Table Of Contents

Previous topic

TurboGears Reference

Next topic

Classes and Functions

Configuration Options

This section reports a reference of various configuration options available inside TurboGears app_cfg or .ini file. As they are automatically extracted from the source code this list might be incomplete until the whole configuration process is updated to automatically declare the expected options.

For example if you want to enable isodates in your application JSON encoder you might want to add to your app_cfg.base_config the following:

base_config['json.isodates'] = True

JSON Encoding

JSONEncoder.configure(isodates=False, custom_encoders=None, **kwargs)

JSON encoder can be configured through AppConfig (app_cfg.base_config) using the following options:

  • json.isodates -> encode dates using ISO8601 format
  • json.custom_encoders -> List of tuples (type, encode_func) to register custom encoders for specific types.

Flash Messages

TGFlash.configure(cookie_name='webflash', default_status='ok', template=<string.Template object at 0x7f84c3a84b90>, js_call='webflash.render()', js_template=<string.Template object at 0x7f84c3a84bd0>)

Flash messages can be configured through AppConfig (app_cfg.base_config) using the following options:

  • flash.cookie_name -> Name of the cookie used to store flash messages
  • flash.default_status -> Default message status if not specified (ok by default)
  • flash.template -> string.Template instance used as the flash template when rendered from server side, will receive $container_id, $message and $status variables.
  • flash.js_call -> javascript code which will be run when displaying the flash from javascript. Default is webflash.render(), you can use webflash.payload() to retrieve the message and show it with your favourite library.
  • flash.js_template -> string.Template instance used to replace full javascript support for flash messages. When rendering flash message for javascript usage the following code will be used instead of providing the standard webflash object. If you replace js_template you must also ensure cookie parsing and delete it for already displayed messages. The template will receive: $container_id, $cookie_name, $js_call variables.

Sessions

class tg.appwrappers.session.SessionApplicationWrapper(handler, config)

Provides the Session Support

The Session Application Wrapper will make a lazy session instance available every request under the environ['beaker.session'] key and inside TurboGears context as session.

Supported options which can be provided by config are:

Caching

class tg.appwrappers.caching.CacheApplicationWrapper(handler, config)

Provides Caching Support.

The Cache Application Wrapper will make a CacheManager instance available every request under the environ['beaker.cache'] key and inside the TurboGears request context as cache.

Supported options which can be provided by config are:

Internationalization

class tg.appwrappers.i18n.I18NApplicationWrapper(handler, config)

Provides Language detection from request and session.

The session language(s) take priority over the request languages.

Supported options which can be provided by config are:
  • i18n.enabled: Whenever language detection is enabled or not.
  • i18n.lang: Fallback language for the application, works both when language detection is enabled or disabled. If this is set and language detection is dislabled, the application will consider that all gettext wrapped strings must be translated to this language.
  • i18n.lang_session_key: Session key from which to read the saved language (tg_lang by default).
  • i18n.no_session_touch: Avoid causing a session save when reading it to retrieve the favourite user language. This is False by default, setting it to False causes TurboGears to save and update the session for each request.

Transaction Manager

class tg.appwrappers.transaction_manager.TransactionApplicationWrapper(handler, config)

Wraps the whole application in zope.transaction transaction manager and rollbacks transaction in case of crashes.

Supported options which can be provided by config are:

  • tm.enabled: Wenever the transaction manager is enabled or not.
  • tm.attempts: Number of times the transaction should be retried if it fails (no retry by default)
  • tm.commit_veto: A function that will be called for every transaction to check if it should abort transaction or let it go. Function signature shoul be: function(environ, status_code, headers) -> bool.

Custom Error Pages

class tg.appwrappers.errorpage.ErrorPageApplicationWrapper(handler, config)

Given an Application it intercepts the response code and shows a custom page.

Supported options are:

  • errorpage.enabled: Whenever the custom error page is enabled or not.
  • errorpage.status_codes: List of HTTP errors that should be trapped. By default 403, 404, 500.
  • errorpage.handle_exceptions: Whenever exceptions should be trapped and treated as a 500 error or not. By default this is True when debug=false.
  • errorapge.path: Path of the controller should be displayed in case of errors. By default /error/document.

Ming Session Manager

class tg.appwrappers.mingflush.MingApplicationWrapper(handler, config)

Automatically flushes the Ming ODMSession.

In case an exception raised during excution it won’t flush the session and it will instead close it throwing away any change.

Supported options which can be provided by config are:

  • tm.autoflush: Whenever to flush session at end of request if no exceptions happened.