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 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 WidgetBrowser.register_controller() decorator.

static WidgetBrowser.register_controller(widget, action)

Registers function to act as a demo controller for a widget

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 widget_url() function.

widgetbrowser.widget_url(widget, action='', prefix=None)

Returns the URL of the controller to perform action on widget.

If no prefix is passed the it will be tried to be fetched from tw.framework.request_local where the WidgetBrowser leaves it on every request.

Example:

>>> from tw.core.base import Widget
>>> widget_url(Widget)
'/tw.core.base.Widget/'
>>> widget_url(Widget())
'/tw.core.base.Widget/'

You can also pass the path of the widget:

>>> widget_url('tw.api.Widget')
'/tw.api.Widget/'
>>> widget_url('tw.api.Widget', 'show')
'/tw.api.Widget/show'
>>> widget_url('tw.api.Widget', 'show', prefix='/widget')
'/widget/tw.api.Widget/show'

Note

You can pass any path the widget can be imported from when passing a string but if you pass a widget instance or subclass then the real module where it is defined will be generated.

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!"