Creating a Widget

Introduction

Creating a widget is a relatively advanced use of ToscaWidgets - first ensure you are familiar with ToscaWidgets in principle. Some things to consider when creating a widget:

• Select a suitable base class. Often, a widget in tw.forms makes a good base class. For example, if you’re creating a widget for a rich text editor, it may be best to use TextArea as the base class.
• Before creating a new widget library, please look at the existing libraries and determine if the widget would best fit within one of these.
• Think carefully about the parameters your widget has, document these, and provide defaults wherever possible.

Creating a Widget Library

The first step is to use paster to create a template directory structure that you can build your library inside. Please follow the convention of naming all ToscaWidgets libraries in lower-case,and beginning with tw. Use the following command:

$ paster create -t toscawidgets tw.mylibrary

Now, to create the library:

• Modify setup.py to include all the dependencies your widget has
• Create your widgets inside tw/mylibrary/widgets.py
• Add tests for your widgets in tests/test_widget.py
• Add samples for your widgets in tw/mylibrary/samples.py so they appear in the widget browser
• Add documentation for your widgets in docs.

You can preview your widgets’ documentation using the WidgetBrowser. Inside your project directory, issue:

$ twbrowser -d docs

See the FAQ for information on sharing your library with the community.