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: ‘’)