Configuration of ToscaWidgets

ToscaWidgets is a powerful and versatile framework. Most of the time, you can simply start using it, especially when running it inside a framework like TurboGears2.

However, some of it’s more advanced features might need activation and tuning through the configuration options. This section explains them.

Basics

All configuration takes place via the passed config-dict to the tw.core.middleware.make_middleware().

They fall into two categories: keys for configuring the middleware, and keys for configuring the host-framework.

See ToscaWidgetsMiddleware and HostFramework for details.

Here we try & focus on specific usecases, and how to configure them.

Using a render-filter

With the key toscawidgets.framework.middleware.render_filter you can pass a callback to the middleware.

This callback will be passed all the resources a given page has been asked to render, and has to return the plain text HTML that will actually do that.

The default-implementation of this filter that is used when you don’t pass anything to the configuration is this:

def render_filter(environ, resource):
    return resource.render()

So it simply invokes render() on the resources, which will render links such as

<script type="text/javascript" src="/toscawidgets/some.package/some/file.js"/>

Now let’s say you want to use a service like google ajax libraries API to render links to the jQuery-framework provided from tw.jquery.

This you could do with the following render-filter:

def render_filter(environ, resource):
    res = ""
    if "google.jsapi" not in environ:
        res += "<script src="http://www.google.com/jsapi"></script>"
    if resource.modname == "tw.jquery" and \
       "jquery-1.3.2" in resource.active_filename():
       res += """<script type="text/javascript">
                    google.load("jquery", "1.3.2");
                 </script>"""
    else:
        res += resource.render()
    return res

As you can see, you can even use the environ to pass state between several calls to the render_filter.

There are many other use-cases for custom render-filters, for example you can serve CDN-links or render HTML or XHTML links, depending on some environ-variable.