This tutorial introduces you to the widget form system by building a
simple application that accepts and displays comments.

The comments are listed on the index page and a link at the bottom of
the page directs the user to add a comment. To keep things simple,
we’re going to skip the database and just keep track of our comments
in memory using a global comments variable.

The comments form itself requires both a name, an email address and a
comment to be entered. If input to one of the fields is missing, the
form is redisplayed along with a message next to the appropriate
field. We’ve tossed in a checkbox field to give an example that
widgets also handle values of other type than strings, i.e. booleans,
integers etc.

Successfully completing a form adds the comment to the global comments
variable and displays a success message on the index page.

This tutorial starts with a pre-built project. Please download and
unpack the provided archive with the complete example project and read
the source code along with the tutorial. For a detailed explanation
on how to create a new project, please read the 20 Minute Wiki
Tutorial.

If you’re not already familiar with the basics of what widgets are,
and how they work, you’ll probably wan to take a look at the widgets
overview page

The single most common use of Widgets in a TurboGears project is in
building forms.

Widgets make form creation really easy, because they address all the important
aspects of form handling:

Defining which fields the form has

Injecting JavaScript and CSS for a field if necessary

Defining which kind of input each field expects

Wrapping the fields into a form

Displaying the form

Validating form input

Displaying validation errors and re-displaying user input

For the purpose of this tutorial, we are interested in two main types
of widgets: simple form field widgets – text inputs and checkboxes
– and compound widgets like the form itself.

Simple form field widgets generally correspond to the default browser
inputs but some, like the date picker, have extra smarts to make your
users’ lives easier. You can get an overview of which widgets are
available on your install by checking out paster tg-info, and you can
find more details about particular widgets by using the toscawidgets
widget browser:

Compound widgets, like forms, usually act as containers for fields. In
particular, a form provides layout (Table or List) for its fields and
is responsible for labels and error display.

There are many other types of standard widgets, and you can create
your own custom widgets, but this is a simple widgets tutorial, so
we’re keeping it simple. For more information about the widgets
framework, you can start reading at the general widgets overview.

With the introduction out of the way, let’s dive into the code. This
is the form field declaration in
formstutorialtg2/controllers/root.py:

classCommentFields(WidgetsList):"""The WidgetsList defines the fields of the form."""name=forms.TextField(validator=validators.NotEmpty())email=forms.TextField(validator=validators.Email(not_empty=True),attrs={'size':30})comment=forms.TextArea(validator=validators.NotEmpty())notify=forms.CheckBox(label="Notify me")

As you can see, the declaration looks quite a bit like a SQLAlchemy
class definition. The CommentFields class declares a list of four
widgets, all of which are simple widgets corresponding to the
similarly named <INPUT> tags in HTML. The first three are required
text fields and the email field requires a well-formed email
address.

Notice that we have not defined a field widget for the submit
button. The TableForm and ListForm widgets take care of this
for you by default and you can tweak it using their submit_text
argument.

Now the above snippet won’t get you a form as is, it’s just a list of
widgets. To build a form, you pass the list of widgets into a form
constructor (both TableForm and ListForm are standard widgets)
and get a compound form widget:

comment_form=forms.TableForm(fields=CommentFields(),action="save")

Maybe you can guess what the extra action argument is for: it
defines the action attribute of the form element in the generated
HTML, which means that submissions from the form will go to
http://mysite/save and will be handled by the save method of
our controller.

Tip

If, for some reason, you do want to manage the submit button
yourself, derive your own widget form class from TableForm or
ListForm and overwrite the submit attribute with your own
instance of a forms.SubmitButton.

You can see that the submit button has no value and will therefore be
displayed with a language dependant default label because we didn’t
set the form’s submit_text.

If you look at the generated FORM element, you’ll also note that its
action attribute is set to the value of the action argument,
which we specified when we created the form instance.

As a convenience, you can override both the action and
submit_text arguments at display time:

${form(action="preview", submit_text='Preview Comment')}

Whether you want to specify action (or submit_text for that
matter) when you create the form or when you display it, depends on
whether you are reusing the form in another context or not and how
closely coupled the form widget and the controller methods handling
the form are in your application.

If you want to preset the form field values - for instance to edit already
existing data - you pass the form values as the first argument:

${form(data, submit_text='Add Comment')}

You can also explicitly specify it as the value keyword argument:

${form(value=data, submit_text='Add Comment')}

Where data is a dictionary of the form:

data=dict(name='Joe',comment='Hello World',notify=True,...)

Displaying forms is nice, but it really doesn’t help you out that
much. Admittedly, some people write entire toolkits to do just this
sort of thing (GWT, Pyjamas), but TurboGears widgets offer you more.

Validation ensures that the values you’re getting are the values your
method is expecting. Sometimes this is critically important, other
times it’s convenient, but quite a bit of time in web programming is
traditionally tied up in displaying a form, processing the form,
validating its values, and – in the event of errors– redisplaying
the form with the errors marked. TurboGears widgets were created
explicitly to solve this problem.

In practice, you get validation by adding validators to your widget
declarations and setting the appropriate decorators on your form
handling method. You can get super-fancy and do it other ways if
necessary, but we’ll take the simple solutions for simple problems
approach here.

#repeat, for convenienceclassCommentFields(WidgetsList):"""The WidgetsList defines the fields of the form."""name=forms.TextField(validator=validators.NotEmpty())email=forms.TextField(validator=validators.Email(not_empty=True),attrs={'size':30})comment=forms.TextArea(validator=validators.NotEmpty())notify=forms.CheckBox(label="Notify me")

If you look at the definition of CommentFields repeated above,
you’ll see that there is a validator for each of the first three
fields. These validators are part of the formencode.validators
package, part of Ian Bicking’s FormEncode project. Since all values
in a form are sent as strings, validators both convert the value to
the appropriate Python type and check that the value matches a
criteria in one step because one usually requires the other. For
example, if your validator requires a numeric input be greater than 5
and you get "10", you have to convert "10" to the int 10
before a meaningful comparison can be made. In this case, we’re not
doing type conversion for any of our fields, but it’s a useful thing
to know.

The first and third fields have a validators.NotEmpty validator,
which explicitly states that they are required fields. The second
field, with a validators.Email validator, is required as well. We
explicitly state this by passing a not_empty=True, but adding a
validator to the field generally makes that field required. The empty
string, for example, is not a valid email address, so the email
validator will fail. You can get validation on non-required fields by
passing an if_empty="defaultvalue" argument to the validator’s
constructor.

@expose()@validate(comment_form,error_handler=add)defsave(self,name,email,comment,notify=False):"""Handle submission from the comment form and save the comment."""comments.add(name,email,comment)ifnotify:flash(_('Comment added! You will be notified.'))else:flash(_('Comment added!'))redirect('/index')

Our method itself takes a set of arguments corresponding to the fields
in the form. Tracking large numbers of fields is very inconvenient, so
it’s common to just use keyword arguments instead:

Using this syntax you get the data as a dictionary and you have to
extract the field values from there. The use of .get() above is
needed for the notify field, since this is not guaranteed to be
included in the data and because there is no validator checking for
its presence, while the other fields will be present for sure if there
was no validation error.

Note

The form handling strips off the default submit field so
that you don’t have to deal with it. If you add your own, it
won’t be stripped.

Finally, the flash method displays a confirmation notice on the
next page the user is redirected to, which is the index page with the
list of comments.

Let’s take another, closer look at the save method. Our interest
now lies not in its contents, but rather the decorators. We can see
that the method is exposed without a template. It does need to be
exposed or Pylons will raise a 404. The lack of a template is fine
because we’re going to redirect the user to another (output-providing)
method depending on whether the input is valid or not.

The @validate() decorator extracts the various validators from the
form, loops through them, and throws an error if problems are
found. We’re glossing over details, but that’s the basic idea.

If @validate() does throw an error, the error_handler method
takes care of them. If a validation error occurs, TurboGears will
store a dictionary of FormEncode validation errors in
tg.tmpl_context.form_errors.

In the example, we’re re-using add so that the form will be
re-displayed if errors occur. Let’s have a look at the add method
again:

@expose(template='formstutorialtg2.templates.add')defadd(self):"""Show the comment form."""iftg.tmpl_context.form_errors:flash('There was a problem with the form!')returndict(form=comment_form)

The error handling method, if desired, could look into the
form_errors dictionary to see which fields validation has failed
and act accordingly. In practice, most form error handlers simply do
what we do here: put up a notification message and display the form
showing the validation errors.

In this tutorial you have learned how to create a simple form widget
composed of several form fields. You have seen how the widget is
passed to the template, displayed and how submissions from the form
are handled in the controller. You have also seen simple validators in
action that simplify error handling for forms substantially.

This tutorial only covers basic widget usage. If you’d like to know
more, explore the widgets overview.

Todo

Difficulty: Easy. previous paragraph referenced “widget browser” and “toolbox”
as links. These do not exist for tg2. Need to add them back in
here when they are eventually re-written.

The code for this example is courtesy of Michele Cella, but the
individual files in the project have been updated to reflect changes
in TurboGears versions over time and were adapted by various authors
with respect to style, design etc.

Note

The comment feature has been disabled on this page due to heavy spamming. If you want to comment on the contents of this page, if you have questions, or want to report an error, please write to the TurboGears mailing list.