Getting Started

Enabling ToscaWidgets

ToscaWidgets is designed to work within a web request life cycle, so some of its features rely on the a current request object to be able to work a keep track of the state of widgets or resources for the whole duration of the request.

For this reason, to start using ToscaWidgets you need to wrap your WSGI application in the tw2.core.middleware.TwMiddleware, which is also used to configure ToscaWidgets itself:

def application(environ, start_response):
    response_headers = [('Content-type', 'text/plain')]
    start_response("200 OK", response_headers)
    return [b"Hello World!"]

from tw2.core.middleware import TwMiddleware
application = TwMiddleware(application)

from wsgiref.simple_server import make_server
httpd = make_server('', 8000, application)
print("Serving on port 8000...")
httpd.serve_forever()

You can also provide all options available to configure ToscaWidgets (those listed in tw2.core.middleware.Config) to TwMiddleware as keyword arguments to change ToscaWidgets configuration:

from tw2.core.middleware import TwMiddleware
application = TwMiddleware(application, debug=False)

Note

Debug mode is enabled by default in ToscaWidgets, so make sure you provide debug=False on production to leverage templates caching and other speedups.

Now that the middleare is in place, you can easily display any widget you want into your application:

from tw2.forms import SingleSelectField

def application(environ, start_response):
    widget = SingleSelectField(options=[1, 2, 3])
    output = widget.display()

    response_headers = [('Content-type', 'text/html')]
    start_response("200 OK", response_headers)
    return [b"<h1>Hello World!</h1>",
            b"<p>Pick one of the options</p>",
            output.encode('ascii')]

from tw2.core.middleware import TwMiddleware
application = TwMiddleware(application)

from wsgiref.simple_server import make_server
httpd = make_server('', 8000, application)
print("Serving on port 8000...")
httpd.serve_forever()

See Widgets and Forms to get started creating widgets and forms.

class tw2.core.middleware.TwMiddleware(app, controllers=None, **config)[source]

ToscaWidgets middleware

This performs three tasks:
  • Clear request-local storage before and after each request. At the start of a request, a reference to the middleware instance is stored in request-local storage.
  • Proxy resource requests to ResourcesApp
  • Inject resources

Configuration Options

class tw2.core.middleware.Config(**kw)[source]

ToscaWidgets Configuration Set

translator
The translator function to use. (default: no-op)
default_engine
The main template engine in use by the application. Widgets with no parent will display correctly inside this template engine. Other engines may require passing displays_on to Widget.display(). (default:string)
inject_resoures
Whether to inject resource links in output pages. (default: True)
inject_resources_location
A location where the resources should be injected. (default: head)
serve_resources
Whether to serve static resources. (default: True)
res_prefix
The prefix under which static resources are served. This must start and end with a slash. (default: /resources/)
res_max_age
The maximum time a cache can hold the resource. This is used to generate a Cache-control header. (default: 3600)
serve_controllers
Whether to serve controller methods on widgets. (default: True)
controller_prefix
The prefix under which controllers are served. This must start and end with a slash. (default: /controllers/)
bufsize
Buffer size used by static resource server. (default: 4096)
params_as_vars
Whether to present parameters as variables in widget templates. This is the behaviour from ToscaWidgets 0.9. (default: False)
debug
Whether the app is running in development or production mode. (default: True)
validator_msgs
A dictionary that maps validation message names to messages. This lets you override validation messages on a global basis. (default: {})
encoding
The encoding to decode when performing validation (default: utf-8)
auto_reload_templates
Whether to automatically reload changed templates. Set this to False in production for efficiency. If this is None, it takes the same value as debug. (default: None)
preferred_rendering_engines
List of rendering engines in order of preference. (default: [‘mako’,’genshi’,’jinja’,’kajiki’])
strict_engine_selection
If set to true, TW2 will only select rendering engines from within your preferred_rendering_engines, otherwise, it will try the default list if it does not find a template within your preferred list. (default: True)
rendering_engine_lookup

A dictionary of file extensions you expect to use for each type of template engine. Default:

{
       'mako':['mak', 'mako'],
       'genshi':['genshi', 'html'],
       'jinja':['jinja', 'html'],
       'kajiki':['kajiki', 'html'],
}
script_name
A name to prepend to the url for all resource links (different from res_prefix, as it may be shared across and entire wsgi app. (default: ‘’)