Introduction

twForms is a form generation library built using ToscaWidgets. Since it is the most used Tosca "widget", twForms is commonly believed to be ToscaWidgets (even I often use the terms interchangeably).

ToscaWidgets is a framework to package and distribute chunks of html templates, javascript, css and the python code that makes them tick. When properly configured, widgets built with ToscaWidgets can be used in any python framework or application that can use WSGI middleware.

This tutorial will focus on its usage on Pylons, however, the core concepts apply equally to any python web framework. The only difference is how TW's middleware is integrated and the detailed steps provided (file paths, etc...)

Scope

This tutorial will cover:

• How to configure ToscaWidgets in Pylons.
• How to build a simple web form using simple fields.
• How to add validators to the form's fields.
• How to use fancy fields which require javascript.

Requirements

This tutorial has been tested with Pylons 0.9.6.1 and Toscawidgets 0.1a2dev_r3534. Any version later than those should work fine too.

Since Mako is the official template language used by Pylons, this tutorial will use Mako templates too. Any python templating engine that implements a python.templating.engine entry-point should be usable too. Both to create custom widgets and to display them on. ToscaWidgets has been tested on Mako, Genshi, Kid and Cheetah.

To make installation easier and better separate the controller layer from the view layer, this tutorial will use lxml to inject resources (css and javascript links) into the html page.

Installation

Use easy_install to install twForms, this should pull ToscaWidgets and all required dependencies too:

easy_install twForms

Pylons >= 0.9.6.1 is assumed to be already instaled.

Configuring ToscaWidgets

Bootstrap an empty Pylons project to follow the rest of the tutorial:

paster create -t pylons TWTutorial

Now you should edit twtutorial.config.middleware to stack TW's middleware.

First of all, at the beginning of the module, import TW's middleware and Pylons' HostFramework object:

1
2

from toscawidgets.middleware import TGWidgetsMiddleware
from toscawidgets.mods.pylonshf import PylonsHostFramework

Now, after the line that says "CUSTOM MIDDLEWARE HERE" inside make_app(), add:

1
2

host_framework = PylonsHostFramework(default_view="mako")
app = TGWidgetsMiddleware(app, host_framework)

You should now be able to launch your app with paster serve --reload development.ini, point your browser to http://localhost:5000/ and see Pylons's default welcome page.

Building your first twForms form

Create a file called widgets.py inside the twtutorial package and type or paste the following code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

from toscawidgets.widgets import forms
from toscawidgets.api import WidgetsList

forms.FormField.engine_name = "mako"

class PostForm(forms.ListForm):
    class fields(WidgetsList):
        title = forms.TextField()
        author = forms.SingleSelectField(
            options = ["Peter", "Lucy"]
            )
        content = forms.TextArea()

post_form = PostForm("post_form")

The above code should be, more or less, self-explanatory:

We create a ListForm subclass (a form which renders its fields in an unordered list, the kind of form CSS fan-boys usually love) which has three fields:

• a TextField, which is a, surprise, single-line text entry field
• a SingleSelectField, which is a drop-down kind of field
• a TextArea, which is a multi-line text entry field

Then we initialize the form class as a module level instance and give it a post_form id. This id will be useful later when we apply CSS selectors or attach javascript event handlers.

Notice that the form is instantiated at import time. This is how widgets are usually instantiated and used (but not neccesarily so). There is no thread-safety issues with the above code because widgets are state-less, that is, once it's initial state is fixed when initialized, it's attributes are never modified again. This does not mean we cannot modify how they're rendered on every request. We can do it by overriding their params when rendering them, more on this later.

One special detail worth mentioning: Notice the line where we modify the engine_name of the FormField class attribute? Well, this is because twForms was initially built using Genshi templates so genshi remains the default template engine used. Roger Demetrescu has kindly ported all twForms' templates to Mako so, in order to avoid the Genshi dependency and obtain a significant speed boost, you can change this class attribute to mako and all widgets inside the twForms package will use their Mako templates.

Displaying the form

To see the markup that the form produces when rendered we can do it directly from the command-line, just import the widgets module we just created and call the post_form instance:

1
2

>>> from twtutorial.widgets import post_form
>>> print post_form()

Produces:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

<form id="post_form" action="" method="post" class="postform">
    <div>
    </div>
    <ul class="field_list" >
        <li class="even">
            <label id="post_form_title.label" for="post_form_title" class="fieldlabel required">Title</label>
            <input type="text" name="title" class="textfield required" id="post_form_title" value="" />
        </li>
        <li class="odd">
            <label id="post_form_author.label" for="post_form_author" class="fieldlabel">Author</label>
            <select name="author" class="singleselectfield" id="post_form_author">
        <option value="Peter">Peter</option>
        <option value="Lucy">Lucy</option>
</select>
        </li>
        <li class="even">
            <label id="post_form_content.label" for="post_form_content" class="fieldlabel">Content</label>
            <textarea id="post_form_content" name="content" class="textarea" rows="25" cols="79"></textarea>
        </li>
        <li class="odd">
            <input type="submit" class="submitbutton" id="post_form_submit" value="Submit" />
        </li>
    </ul>
</form>

I hope the above hints one of the benefits twForms provides over writting forms using plain old HTML: Valid, accesible, easily maintainable markup with just a little over 5 lines of code.

Using the form in your application

Lets create a new controller and a mako template to use the this form in our application. First the controller:

paster controller tutorial

Now edit twtutorial.controllers.tutorial so it looks like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

import logging

from twtutorial.lib.base import *

log = logging.getLogger(__name__)

class TutorialController(BaseController):

    def index(self):
        return render('/tutorial.mako')

And add a file called tutorial.mako inside the templates folder with the following code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

<%!
    from twtutorial.widgets import post_form
%>

<html>
    <head>
        <title>ToscaWidgets Tutorial</title>
    </head>
    <body>
        <h1>Welcome to the ToscaWidgets tutorial!</h1>
        ${post_form()}
    </body>
</html>

You should now be able to point your browser to http://localhost:5000/tutorial and see the form we just created.

Using the form to validate input

What we have just covered doesn't provide much more value than what using mako functions or webhelpers to generate the fields markup would have provided.

However, twForms integrates nicely with FormEncode (does not replace it!) to have the objects which will validate our input near the fields they're validating.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

from toscawidgets.widgets.forms.validators import UnicodeString, Email
# All other imports...

class PostForm(forms.ListForm):
    class fields(WidgetsList):
        title = forms.TextField(
            validator = UnicodeString(not_empty=True)
            )
        email = forms.TextField(
            validator = Email(not_empty=True)
            )
        author = forms.SingleSelectField(
            options = ["Peter", "Lucy"]
            )
        content = forms.TextArea()

${post_form(action=h.url_for(controller='tutorial', action='save'))}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

from pprint import pformat
from toscawidgets.mods.pylonshf import validate
from twtutorial.widgets import post_form

@validate(form=post_form, error_handler="index")
def save(self):
    response.headers['Content-Type'] = 'text/plain'
    try:
        return pformat(self.form_result)
    except AttributeError:
        return "You must POST to this method, dummy!"

Using fancy fields

I'll finally cover in this tutorial how we can enhance our form with some fancy fields which use Javascript to enhance the user's experience.

easy_install lxml

1

app = TGWidgetsMiddleware(app, host_framework, inject_resources=True)

easy_install twTinyMCE

1

from toscawidgets.widgets.tinymce import TinyMCE

1
2
3
4

class PostForm(forms.ListForm):
    class fields(WidgetsList):
        # Other fields...
        content = TinyMCE()

Colophon

I hope this tutorial has made the whole ToscaWidgets world less daunting. There is much more to cover which I hope to do soon in following tutorials.

For the meantime you can:

• subscribe to the ToscaWidgets mailing list and drop your comments, questions, flames and praises.

• Check out the API docs included in the docstrings. I recommend plain old pydoc for this:

  pydoc toscawidgets.widgets.forms
  

• Check out a more elaborate example.

• Read the source! The Most Authoritative Documentation you'll ever find! :)

Coming next

• How to use forms to edit your SQLAlchemy or SQLObject instances.
• How to use repeated fields and fieldsets to handle related objects in the same form.
• How to tweak the form's template to precisely control its layout.
• How to create your own form fields specifically tailored to your app.
• How to create a widget package so you can reuse it in different apps and/or distribute it (eg: twTinyMCE).
• How to create widgets (non form fields) to add common UI elements (tree menu, search box,...) to your app.
• How to programatically generate forms by introspecting your business objects.
• How to use FormEncode schemas to validate more than one field simultaneously.
• .... want something else covered? Drop a line at the mailing list.

Want to help out with these tutorials? By all means, drop me a line!