Section 16.2. Form Widgets


16.2. Form Widgets

Form 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 Layout

As 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 Widgets

As 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.

  • AutoComplete provides a list of possible selections that is dynamically updated as you type. The list of possible selections is provided by a search controller method that returns a JSONified list to the page. We'll explore this widget in more detail in section 16.7, "Anatomy of an Ajax Widget."

  • Button renders a generic button. It serves as a superclass for the SubmitButton, ResetButton, and ImageButton fields. You can subclass it to create your own custom button fields, too.

  • SubmitButton renders the submit button for a form.

  • ResetButton clears the data from the associated form.

  • ImageButton this button has an image on it.

  • CheckBox renders a simple checkbox field to your form.

  • CheckBoxList renders several checkboxes.

  • CalendarDateTimePicker renders a dynamic calender display that allows you to pick a date and time.

  • CalendarDatePicker just like the CalendarDateTimePicker, but only allows you to pick a date not the time.

  • HiddenField adds a hidden field to your form. Hidden fields can be an easy way to make sure data is passed back to the server with the form.

  • PasswordField displays a password type field where the characters the user types are not displayed.

  • RadioButtonList displays a radio button.

  • SingleSelectField displays a select field.

  • MultipleSelectField displays a select field that allows you to select multiple options.

  • TextArea displays a text area.

  • TextField displays a text field.

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.




Rapid Web Applications with TurboGears(c) Using Python to Create Ajax-Powered Sites
Rapid Web Applications with TurboGears: Using Python to Create Ajax-Powered Sites
ISBN: 0132433885
EAN: 2147483647
Year: 2006
Pages: 202

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net