tw2.devtools

To keep tw2.core as minimal as possible, features needed only for development are in a separate package, tw2.devtools. The features in devtools are:

• Widget browser
• Widget library quick start

Widget Browser

The browser essentially enumerates the tw2.widgets entrypoint. When browsing a module, it iterates through the public names in the module, and displays any that is a Widget subclass. It also imports samples.py for demo widgets. This can contain page_options - a dict that gives attributes for the body tag in the containing page.

The parameters that are displayed are: all the required parameters, plus non-required parameters that are defined on anything other than the Widget base class. Variables are never shown.

Widget Library Quick Start

To create a widget library, issue:

$ paster create -t tw2.library tw2.mylib

This creates an empty template that gets you started.

Writing a good widget library

Widget browser

This is the main documentation for the library, and it needs to give a good introduction to a new user. Every widget should have a demo, and a clear description of the widget and parameters.

Example application

There should be a simple example application that demonstrates the widgets in action. Ideally this should just be a single python file that works standalone.

Parameters

Every widget should have a convenient set of parameters that allow common customisation with ease, and make more complex configuration possible.

Validation

Every widget needs to work correctly with validation. When a form is submitted and there is a validation failure, all widgets should maintain the same appearance. This includes a widget with no value continuing to have no value.

Growing

Every widget should work correctly within a tw2.dynforms Growing container.

Database interaction

Some widgets (e.g. AjaxLookup, DataGrid) can benefit from built-in database interaction. In this case, the widget library must include a base widget that does no database interaction, so it can be connected to any database/ORM. The library should include a widget that interacts with SQLAlchemy, and may include a widget that interacts with any other database/ORM.