.. _create:

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.
   
.. _existing libraries: http://www.toscawidgets.org/hg

    
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.

.. _FAQ: faq.html