.. _demo_howto:

Writting a widget demo
======================

A widget demo is a widget subclass designed to show a demo of a widget. In its
most basic form it just subclasses the widget it wants to demo and provide
default value and parameters to show the widget off.

Demo widgets
------------

The widget browser instantiates widgets **with no parameters**, so all
configuration must be done by the demo widget itself.

Example::

    from tw.forms import TextField

    class DemoTextField(TextField):
        default = "I am a text field!"


.. _demo_controller:

Demo controllers
----------------

Widgets which need a controller to feed them data can register a controller that
the widgetbrowser will mount and make available. To register it use the
:meth:`WidgetBrowser.register_controller` decorator.

.. automethod:: widgetbrowser.wsgiapp.WidgetBrowser.register_controller

Example::
    
    class MyDemoWidget(Widget): pass

    @WidgetBrowser.register_controller(MyDemoWidget, 'pull_data')
    def send_data(request, response):
        widget = request.widget
        return "Sending data to %r" % widget

The `request` and `repsonse` parameters are WebOb `Request` and `Response`
objects. Note that we can access the widget instance at `request.widget`.

The controller function can return a string, which will be used as the
reponse's body or a WSGI app which will take over the response process.

To obtain the URL of a demo controller from inside a widget (to configure the
URL AJAX request should fetch from) use the :func:`widget_url` function.

.. autofunction:: widgetbrowser.widget_url

Adding tabs to the widgetbrowser
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To add a new tab to the widget browser of a particular widget just write a
controller and register it using the tab names as action. For example, a
`widgetbrowser` directive like::
    
    .. widgetbrowser:: tw.somewidget.Fooo
       :tabs: demo, foozings

Will create a tab called `Foozings` which will be served by a controller
registered like this::

    from widgetbrowser import WidgetBrowser
    from tw.something import Fooo

    @WidgetBrowser.register_controller(Fooo, 'foozings')
    def foozingize(request, response):
        return "Hello Foozer!"