Introduction

ToscaWidgets is a web widget toolkit for Python to aid in the creation, packaging and distribution of common view elements normally used in the web.

History

ToscaWidgets is an almost complete rewrite of the widgets package bundled with TurboGears 1.0. The rewrite's goal was to decouple the widgets package from CherryPy and TurboGears itself to fit better with TurboGears 2.0 philosophy which is to partition it's services into independent WSGI components for easier mainteinance and reuse in other Python web applications or frameworks.

It seems ToscaWidgets has well achieved this goal as there it has been tested to interoperate nicely in TurboGears 1.0b2, Pylons 0.9.4 and a simple WSGI app served by Paste. There are reports that it is being used succesfully with WebPy too. Check this SVN folder out for examples of app/framework integration.

Why use it?

Usually web-applications employ a series of patterns to provide GUI elements (widgets) to their users in order to make their experience easier, more intuitive and pleasant. These patterns are normally implemented using different inter-related technologies which when combined provide the final output the user sees:

• HTML:

  For semantic structure. Without it we wouldn't even call it a web-page ;)

• CSS:

  For visual layout and styling. Plain HTML looks ugly.

• JavaScript:

  For client-side scripting. In these buzzw.. err, Web 2.0 days every web-application must provide a rich experience to their users or they'll surf elsewhere.

• Server-side scripting:

  Does the hard work. Retrieves data from a database, performs the app's logic and generates the neccesary markup to glue everything together and send it to the user's browser.

When implementing a widget all these pieces need to be served together and kept in sync when changes are made. This can be a maintenance nightmare if not well planned and done with parsimonious discipline, and surely makes code reuse harder as you have 4 pieces of code in 4 different languages lying around which you need to pack together and include in every rendered page that needs them.

Well, this is the gap ToscaWidgets is designed to fill. ToscaWidgets let's you declare a widget (GUI element, or View element, the "V" in MVC) which encapsulates the template that will generate the HTML, the CSS that will give the widget it's look & feel, the JavaScript that will seduce your users and the Python code that will interface it with the rest of your application.

Thanks to SetupTools all of this can be nicely packed into an EGG and reused with ease in any web-application that needs it. You can also easily share it with the rest of the world if your altruistic inclinations demand it.

Features

• Can "scaffold" a bare-bones EGG for you to fill in and get up started quickly, thanks to PasteScript.
• HTML templates can be written in any template language of your choice as long as it's supported by the Buffet plugin API and has a python.templating.engines entry-point defined. Currently templates written in Genshi, Kid, Cheetah, Mako and plain Python string.Template have been tested.
• If the framework supports it, CSS and JavaScript links are included automatically in every page that needs them. When using Genshi this is done by XIncluding a master template and when using Kid it is done by extending one. Those base templates define match functions that will take care of rendering the links and sources. Take a look at the examples directory in the source distrubution to see how it can be implemented.
• Resources (CSS & JS files) are automatically served by a piece of WSGI middleware which also takes care of interfacing with the hosting app/framework. Thanks to Paste
• The twForms package which builds on ToscaWidgets nicely integrates FormEncode so you can attach a validator to every form input field that needs one. The form will take of generating a FormEncode Schema so you can easily validate the input it will send to your application minimizing chances of invalid or malicious input compromising your data.
• Easily extensible and customizable thanks to the well-thought use of generic functions (provided by RuleDispatch)
• Pythonic javascript API provided by MochiKit (Available as a separate package: twMochikit). Other javascript API's are easily wrapped as widgets, Matt Good is working on a jQuery wrapper (available at SVN).
• There's an API for generating JS calls programatically from Python to initialize JS requiring widgets, connecting event handlers, etc... It is not meant to code JS in Python but to provide an interface to call JS code from Python (more or less like SWIG does to bridge the gap between C(++) and Python)
• Liberally licensed under the MIT License which basically says that you can use this code for anything you want. Both open-source and closed commercial projects.

Planned Features

• A widget-browser to develop and test widgets outside of your app. Will also serve as live demo and a place to read the widgets' docs.
• twForms will provide more JS-using/AJAX widgets in the near future.

Download and Install

ToscaWidgets can be downloaded and installed with setuptools' easy_install:

easy_install ToscaWidgets

You will probably also want to install the form related widgets. You can do so by:

easy_install twForms

The latest development version (which you are encouraged to use and submit patches against) is available in a Subversion repository

ToscaWidgets supports Cheetah (via TurboCheetah), Kid (via TurboKid), Genshi and Mako templates (and other Buffet-compatible templating engines), if these packages are installed. You may optionally install them as ToscaWidgets dependencies:

easy_install ToscaWidgets[cheetah,kid,genshi,mako]
easy_install ToscaWidgets[cheetah,kid]
...

Credits

ToscaWidgets has been developed by Alberto Valverde Gonzalez based on the work of the many people involved in developing, testing and designing TurboGears' Widgets.

The original design was made by TurboGears' author, Kevin Dangoor.

Michele Cella and myself worked hard to push TG's implementation to where it now stands.

State of the API

ToscaWidgets has recently entered it's alpha stage. The API is mostly frozen and backwards compatibility is a priority now. Any API tweaks that might pop up will provide aliases and DeprecationWarnings in order not to break client code that uses them.

Mailing List

ToscaWidgets and related packages can be discussed in the mailing list.

Contributing

Please submit patches and bug reports to the TurboGears Trac, file them under the ToscaWidgets component and 2.0 Milestone.