.. _configuration:

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 
:func:`tw.core.middleware.make_middleware`. 

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

See :class:`~tw.core.middleware.ToscaWidgetsMiddleware` and
:class:`~tw.mods.base.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

.. code-block:: html

  <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.



.. _`tw.jquery`: http://toscawidgets.org/documentation/tw.jquery/
.. _`google ajax libraries API`: http://code.google.com/apis/ajaxlibs/