Section 7.3. Adding a New Project

7.3. Adding a New Project

The Dashboard isn't just a place to display existing projects, it also provides a way to quickly add a new project to your database.

Rather than have a form for adding a new project always sitting there taking up space in the dashboard form, the WhatWhat developers created a JavaScript function that toggles the form between hidden (its default state) and visible.

Here's the code in dashboard.kid to display the form:

The sample bookmarker application uses the TurboGears form widget to automatically generate our forms, but the WhatWhat project takes another approach and creates the form by hand. The authors of WhatWhat create a table and the input fields, and handle the form action themselves. The action attribute tells us that this is going to be posted to our web server, to new_project, which will call that method in our dashboard controller. (I told you we'd get back to it!) If you've ever written an HTML form before, this is going to look pretty familiar to you. The only TurboGears-specific stuff in here is the py:for loop that generates the list of options in the contact_id field.

There is a middle way, between accepting the restriction of automatic form rendering on your page and doing things by hand the way WhatWhat does. And in most cases, this middle way is the most efficient method to manage forms because you get all the power of widgets to handle their own validation errors along with total control of the placement of the fields on the page.

Chapter 20, "Internationalization," covers this in detail. For now, however, we content ourselves with a quick example.

Suppose you create a new Project form from a controller that looks like this:

class ProjectFields(widgets.WidgetsList):     title = TextField(label="Project", validator=validators.NotEmpty())     client_revenue = widgets.TextField(validator=validators.Number())     project_form = widgets.TableForm(fields=ProjectFields(),                                      action="save_project_test")

You could then write code such as this in your template:

<div py:content="form.display_field_for('title', value=product.title)" />     <div py:content="form.display_field_for('Client Revenue', value=product. client_revenue)" />

You might have to work a little bit to wrap your mind around widgets. When you get used to using them, however, you will quickly see their benefits. Widgets do a lot of the hard work for you, including the following:

• Automatically render the right kind of field in your form

• Enable you to use widgets such as the AutoComplete widget that require special JavaScript components

• Render validation error messages for each field on their own

That said, TurboGears widgets are never required, and you can always do what WhatWhat does and roll your own forms. For example, if you are showing a bunch of PHP programmers how to write TurboGears applications, this way of doing forms is going to seem a lot more familiar to them and will make the first step of the transition easier.

The final section of the dashboard.kid template is pretty simple:

<h3>Archived Projects</h3> <a href="#"  onclick="toggle('archived_projects');toggle('show_ archived');toggle('hide_archived'); return false;">show archived projects</a> <a href="#" style="display: none"  onclick="toggle('archived_ projects');toggle('show_archived');toggle('hide_archived'); return false;">hide archived projects</a> <div style="display: none" >   <div  onclick="document.location.href='${tg.url('/ project/%s' % project.id)}'" py:for="project in archived_projects">     <div >       <h3 py:content="project.name" />       <span >Archived</span>     </div>   </div> </div> </body> </html>

Its job is to create a list of all the archived projects in the database, and display it only if the user clicks the Show Archived Projects link. In Section 7.4, we look at the JavaScript helper libraries used in WhatWhat, and how they are called on this page to dynamically show and hide page sections.