16.2. Form WidgetsForm Widgets contain any number of form field elements. These elements are contained in a WidgetsList that contains all the form elements you want. A WidgetsList is like a Python list, so you can append new widgets to it dynamically, but remember this list will be rendered the same way for all incoming requests. So, in general, it's okay to create the WidgetsList pragmatically, but don't go around changing it after you've instantiated a form object with it, without thinking through the thread safety issues. You might remember our widget example from Chapter 5: class bookmark_fields(widgets.WidgetsList): bookmark_name = widgets.TextField(validator=validators.NotEmpty) link = widgets.TextField(validator=validators.URL) description = widgets.TextArea(validator=validators.NotEmpty) bookmark_form = widgets.TableForm(fields=bookmark_fields(), submit_text="Save Bookmark") The first thing to notice here is that we create a simple WidgetsList that contains references to each of the fields we want in our form, along with whatever validators we want to use for that field. Then, we create a new TableForm widget instance called bookmark_form by passing in the list of fields to the form widget's fields param and setting the text we want to show up on the submit button. If that's all you could do with form widgets, there would be a lot of cases where you might feel the need to write your forms by hand. Fortunately, widgets provide plenty of mechanisms for customization. So, unless your requirements are very strange, you should be able to get the form widget to do whatever you want. 16.2.1. Custom Form LayoutAs we've already seen, it is easy to just take a list of form elements and build a WidgetList, pass it to your form and have everything automatically generated for you. But, what do you do when you want to customize the layout of the resulting form? Fortunately, TurboGears form widgets have a built mechanism that makes creating custom form templates easy. If you have defined this form in your controller: from turbogears import widgets class MyForm(widgets.Form): template = "widgets.templates.wikiform" fields = [widgets.CalendarDateTimePicker("date"), widgets. TinyMCEWidget("text")] You can create a wikiform.kid template which lets you pick exactly where to render each of the widgets in your form. <form xmlns:py="http://purl.org/kid/ns#" name="${name}" action="${action}" method="${method}" py:attrs="form_attrs"> <h1> Choose the Date from the Calendar: </h1> ${display_field_for("date")} <h1> Enter some interesting text: >/h1> ${display_field_for("text")} </form> You can then render that form on any page, in the same way that you would render any other form. This provides you with total control of the way your form will be displayed on your final page. In this case you'll get two fields, both of which include some complex JavaScript stuff. The first provides a calendar pop-up for you to use to select the date you want. The second is a third-party widget that you can download from www.turbogears.org/cogbin, and it provides a nice WYSIWYG text editor. 16.2.2. Form Field WidgetsAs we've already seen, TurboGears provides a number of interesting widgets for use in your forms. The basics are definitely covered with a matching widget for each of the HTML form element types. But, as we just saw, there are a few extra form filed widgets, which TurboGears provides to make creating dynamic web applications easier.
In the TurboGears ToolBox (which will be explored in depth in Chapter 19, "The TurboGears Toolbox and Other Tools") there's a Widget Browser tool that shows each of the installed widgets, along with descriptions, sample code, and the template code for that widget. You can use the Widget Browser to learn more about each of the above widgets, but there's another more important reason to check out the Widget Browserit displays all installed widgets, not just the built in widgets mentioned here. It's possible to package up a widget into a reusable component, and upload it to a central Python repository known as the Cheese Shop. These widgets are then automatically made available to you for easy_install. You can see a list of all the available thrid party widgets in the "CogBin" portion of the TurboGears website (www.turbogears.org/cogbin/). Once you download and install a widget, it will automatically show up in the Widget Browser. So while we've provided brief descriptions of each of the form field widgets, the Widget Browser will provide descriptions for all kinds of other widgets, including all of the third-party widgets you've installed. |