[This is reference documentation. If you haven't yet read "Lesson 5: widgets" of demo.txt, you should go and do so now. This document also assumes you have a good understanding of HTML forms and form elements. If not, you could do worse than pick up a copy of HTML: The Definitive Guide by Chuck Musciano & Bill Kennedy (O'Reilly). I usually keep it within arm's reach.]
Web forms are built out of form elements: string input, select lists, checkboxes, submit buttons, and so forth. Quixote provides a family of classes for handling these form elements, or widgets, in the quixote.form.widget module. The class hierarchy is:
Widget [A] | +--StringWidget | | | +--PasswordWidget | | | +--NumberWidget [*] [A] | | | +-FloatWidget [*] | +-IntWidget [*] | +--TextWidget | +--CheckboxWidget | +--SelectWidget [A] | | | +--SingleSelectWidget | | | | | +-RadiobuttonsWidget | | | | | +-OptionSelectWidget [*] | | | +--MultipleSelectWidget | +--SubmitButtonWidget | +--HiddenWidget | +--ListWidget [*] [*] Widget classes that do not correspond exactly with a particular HTML form element [A] Abstract classes
Widget is the abstract base class for the widget hierarchy. It provides the following facilities:
The Widget constructor signature is:
Widget(name : string, value : any = None)
The Widget base class also provides a couple of useful methods:
The following two methods will be used on every widget object you create; if you write your own widget classes, you will almost certainly have to define both of these:
Used for short, single-line string input with no validation (ie. any string will be accepted.) Generates an <input type="text"> form element.
StringWidget(name : string, value : string = None, size : int = None, maxlength : int = None)
>>> StringWidget("foo", value="hello").render(request) '<input name="foo" type="text" value="hello">' >>> StringWidget("foo", size=10, maxlength=20).render(request) '<input name="foo" type="text" size="10" maxlength="20">'
PasswordWidget is identical to StringWidget except for the type of the HTML form element: password instead of text.
Used for multi-line text input. The value is a single string with newlines right where the browser supplied them. (\r\n, if present, is converted to \n.) Generates a <textarea> form element.
TextWidget(name : string, value : string = None, cols : int = None, rows : int = None, wrap : string = "physical")
Used for single boolean (on/off) value. The value you supply can be anything, since Python has a boolean interpretation for all values; the value returned by parse() will always be 0 or 1 (but you shouldn't rely on that!). Generates an <input type="checkbox"> form element.
CheckboxWidget(name : string, value : boolean = false)
>>> CheckboxWidget("foo", value=0).render(request) '<input name="foo" type="checkbox" value="yes">' >>> CheckboxWidget("foo", value="you bet").render(request) '<input name="foo" type="checkbox" value="yes" checked>'
Used to select a single value from a list that's too long or ungainly for a set of radiobuttons. (Most browsers implement this as a scrolling list; UNIX versions of Netscape 4.x and earlier used a pop-up menu.) The value can be any Python object; parse() will return either None or one of the values you supply to the constructor as allowed_values. Generates a <select>...</select> tag, with one <option> tag for each element of allowed_values.
SingleSelectWidget(name : string, value : any = None, allowed_values : [any] = None, descriptions : [string] = map(str, allowed_values), quote : boolean = true, size : int = None)
>>> widget = SingleSelectWidget("foo", allowed_values=["abc", 123, 5.5]) >>> print widget.render(request) <select name="foo"> <option value="0">abc <option value="1">123 <option value="2">5.5 </select> >>> widget = SingleSelectWidget("bar", value=val2, allowed_values=[val1, val2, val3], descriptions=["foo", "bar", "foo & bar"], size=3) >>> print widget.render(request) <select name="bar" size="3"> <option value="0">foo <option selected value="1">bar <option value="2">foo & bar </select>
Used to select multiple values from a list. Everything is just like SingleSelectWidget, except that value can be a list of objects selected from allowed_values (in which case every object in value will initially be selected). Generates a <select multiple>...</select> tag, with one <option> tag for each element of allowed_values.
MultipleSelectWidget(name : string, value : any | [any] = None, allowed_values : [any] = None, descriptions : [string] = map(str, allowed_values), quote : boolean = true, size : int = None)
The first derived widget class: this is a subclass of StringWidget specifically for entering integer values. As such, this is the first widget class we've covered that can reject certain user input. (The selection widgets all have to validate their input in case of broken or malicious clients, but they just drop bogus values.) If the user enters a string that Python's built-in int() can't convert to an integer, IntWidget's parse() method raises FormValueError (also defined in the quixote.form.widget module). This exception is handled by Quixote's form framework, but if you're using widget objects on their own, you'll have to handle it yourself.
IntWidget.parse() always returns an integer or None.
IntWidget(name : string, value : int = None, size : int = None, maxlength : int = None)
Constructor arguments are as for StringWidget, except that value must be an integer (or None). Note that size and maxlength have exactly the same meaning: they control the size of the input widget and the maximum number of characters of input.
>>> IntWidget("num", value=37, size=5).render(request) '<input type="string" name="num" value="37" size="5">'
FloatWidget is identical to IntWidget, except:
For example, if you're asking a user for their address, some of the details will vary depending on which country they're in. You might make the country widget an OptionSelectWidget: if the user selects "Canada", you'll ask them for a province and a postal code; if they select "United States", you ask for a state and a zip code; and so forth. (I don't really recommend a user interface that works this way: you'll spend way too much time getting the details right ["How many states does Australia have again?"], and you're bound to get something wrong -- there are over 200 countries in the world, after all.)
$Id: widgets.txt,v 1.7 2002/10/02 17:00:44 gward Exp $