The packages names have changed in Quixote 2.
Quixote form1 forms are now in the package quixote.form1. (In Quixote 1, they were in quixote.form.)
Quixote form2 forms are now in the package quixote.form. (In Quixote 1, they were in quixote.form2.)
These are some notes and examples for converting Quixote form1 forms, that is forms derived from quixote.form1.Form, to the newer form2 forms.
Form2 forms are more flexible than their form1 counterparts in that they do not require you to use the Form class as a base to get form functionality as form1 forms did. Form2 forms can be instantiated directly and then manipulated as instances. You may also continue to use inheritance for your form2 classes to get form functionality, particularly if the structured separation of process, render, and action is desirable.
There are many ways to get from form1 code ported to form2. At one end of the spectrum is to rewrite the form class using a functional programing style. This method is arguably best since the functional style makes the flow of control clearer.
The other end of the spectrum and normally the easiest way to port form1 forms to form2 is to use the compatibility module provided in the form2 package. The compatibility module's Form class provides much of the same highly structured machinery (via a handle master method) that the form1 framework uses.
Here's the short list of things to do to convert form1 forms to form2 using compatibility.
Import the Form base class from quixote.form.compatibility rather than from quixote.form1.
Getting and setting errors is slightly different. In your form's process method, where errors are typically set, form2 has a new interface for marking a widget as having an error.
Form1 API:
self.error['widget_name'] = 'the error message'Form2 API:
self.set_error('widget_name', 'the error message')If you want to find out if the form already has errors, change the form1 style of direct references to the self.errors dictionary to a call to the has_errors method.
Form1 API:
if not self.error: do some more error checking...Form2 API:
if not self.has_errors(): do some more error checking...Form2 select widgets no longer take allowed_values or descriptions arguments. If you are adding type of form2 select widget, you must provide the options argument instead. Options are the way you define the list of things that are selectable and what is returned when they are selected. the options list can be specified in in one of three ways:
options: [objects:any] or options: [(object:any, description:any)] or options: [(object:any, description:any, key:any)]An easy way to construct options if you already have allowed_values and descriptions is to use the built-in function zip to define options:
options=zip(allowed_values, descriptions)Note, however, that often it is simpler to to construct the options list directly.
- You almost certainly want to include some kind of cascading style sheet (since form2 forms render with minimal markup). There is a basic set of CSS rules in quixote.form.css.
Here's the longer list of things you may need to tweak in order for form2 compatibility forms to work with your form1 code.
widget_type widget class attribute is gone. This means when adding widgets other than widgets defined in quixote.form.widget, you must import the widget class into your module and pass the widget class as the first argument to the add_widget method rather than using the widget_type string.
The action_url argument to the form's render method is now a keyword argument.
If you use OptionSelectWidget, there is no longer a get_current_option method. You can get the current value in the normal way.
ListWidget has been renamed to WidgetList.
There is no longer a CollapsibleListWidget class. If you need this functionality, consider writing a 'deletable composite widget' to wrap your WidgetList widgets in it:
class DeletableWidget(CompositeWidget): def __init__(self, name, value=None, element_type=StringWidget, element_kwargs={}, **kwargs): CompositeWidget.__init__(self, name, value=value, **kwargs) self.add(HiddenWidget, 'deleted', value='0') if self.get('deleted') != '1': self.add(element_type, 'element', value=value, **element_kwargs) self.add(SubmitWidget, 'delete', value='Delete') if self.get('delete'): self.get_widget('deleted').set_value('1') def _parse(self, request): if self.get('deleted') == '1': self.value = None else: self.value = self.get('element') def render(self): if self.get('deleted') == '1': return self.get_widget('deleted').render() else: return CompositeWidget.render(self)
Congratulations, now that you've gotten your form1 forms working in form2, you may wish to simplify this code using some of the new features available in form2 forms. Here's a list of things you may wish to consider:
In your process method, you don't really need to get a form_data dictionary by calling Form.process to ensure your widgets are parsed. Instead, the parsed value of any widget is easy to obtain using the widget's get_value method or the form's __getitem__ method. So, instead of:
form_data = Form.process(self, request) val = form_data['my_widget']You can use:
val = self['my_widget']If the widget may or may not be in the form, you can use get:
val = self.get('my_widget')It's normally not necessary to provide the action_url argument to the form's render method.
You don't need to save references to your widgets in your form class. You may have a particular reason for wanting to do that, but any widget added to the form using add (or add_widget in the compatibility module) can be retrieved using the form's get_widget method.
The best way to get started on a functional version of a form2 rewrite is to look at a trivial example form first written using the form1 inheritance model followed by it's form2 functional equivalent.
First the form1 form:
class MyForm1Form(Form):
def __init__(self, request, obj):
Form.__init__(self)
if obj is None:
self.obj = Obj()
self.add_submit_button('add', 'Add')
else:
self.obj = obj
self.add_submit_button('update', 'Update')
self.add_cancel_button('Cancel', request.get_path(1) + '/')
self.add_widget('single_select', 'obj_type',
title='Object Type',
value=self.obj.get_type(),
allowed_values=list(obj.VALID_TYPES),
descriptions=['type1', 'type2', 'type3'])
self.add_widget('float', 'cost',
title='Cost',
value=obj.get_cost())
def render [html] (self, request, action_url):
title = 'Obj %s: Edit Object' % self.obj
header(title)
Form.render(self, request, action_url)
footer(title)
def process(self, request):
form_data = Form.process(self, request)
if not self.error:
if form_data['cost'] is None:
self.error['cost'] = 'A cost is required.'
elif form_data['cost'] < 0:
self.error['cost'] = 'The amount must be positive'
return form_data
def action(self, request, submit, form_data):
self.obj.set_type(form_data['obj_type'])
self.obj.set_cost(form_data['cost'])
if submit == 'add':
db = get_database()
db.add(self.obj)
else:
assert submit == 'update'
return request.redirect(request.get_path(1) + '/')
Here's the same form using form2 where the function operates on a Form instance it keeps a reference to it as a local variable:
def obj_form(request, obj):
form = Form() # quixote.form.Form
if obj is None:
obj = Obj()
form.add_submit('add', 'Add')
else:
form.add_submit('update', 'Update')
form.add_submit('cancel', 'Cancel')
form.add_single_select('obj_type',
title='Object Type',
value=obj.get_type(),
options=zip(obj.VALID_TYPES,
['type1', 'type2', 'type3']))
form.add_float('cost',
title='Cost',
value=obj.get_cost(),
required=1)
def render [html] ():
title = 'Obj %s: Edit Object' % obj
header(title)
form.render()
footer(title)
def process():
if form['cost'] < 0:
self.set_error('cost', 'The amount must be positive')
def action(submit):
obj.set_type(form['obj_type'])
obj.set_cost(form['cost'])
if submit == 'add':
db = get_database()
db.add(self.obj)
else:
assert submit == 'update'
exit_path = request.get_path(1) + '/'
submit = form.get_submit()
if submit == 'cancel':
return request.redirect(exit_path)
if not form.is_submitted() or form.has_errors():
return render()
process()
if form.has_errors():
return render()
action(submit)
return request.redirect(exit_path)
As you can see in the example, the function still has all of the same parts of it's form1 equivalent.
- It determines if it's to create a new object or edit an existing one
- It adds submit buttons and widgets
- It has a function that knows how to render the form
- It has a function that knows how to do error processing on the form
- It has a function that knows how to register permanent changes to objects when the form is submitted successfully.
In the form2 example, we have used inner functions to separate out these parts. This, of course, is optional, but it does help readability once the form gets more complicated and has the additional advantage of mapping directly with it's form1 counterparts.
Form2 functional forms do not have the handle master-method that is called after the form is initialized. Instead, we deal with this functionality manually. Here are some things that the handle portion of your form might need to implement illustrated in the order that often makes sense.
- Get the value of any submit buttons using form.get_submit
- If the form has not been submitted yet, return render().
- See if the cancel button was pressed, if so return a redirect.
- Call your process inner function to do any widget-level error checks. The form may already have set some errors, so you may wish to check for that before trying additional error checks.
- See if the form was submitted by an unknown submit button. This will be the case if the form was submitted via a JavaScript action, which is the case when an option select widget is selected. The value of get_submit is True in this case and if it is, you want to clear any errors and re-render the form.
- If the form has not been submitted or if the form has errors, you simply want to render the form.
- Check for your named submit buttons which you expect for successful form posting e.g. add or update. If one of these is pressed, call you action inner function.
- Finally, return a redirect to the expected page following a form submission.
These steps are illustrated by the following snippet of code and to a large degree in the above functional form2 code example. Often this handle block of code can be simplified. For example, if you do not expect form submissions from unregistered submit buttons, you can eliminate the test for that. Similarly, if your form does not do any widget-specific error checking, there's no reason to have an error checking process function or the call to it:
exit_path = request.get_path(1) + '/'
submit = form.get_submit()
if not submit:
return render()
if submit == 'cancel':
return request.redirect(exit_path)
if submit == True:
form.clear_errors()
return render()
process()
if form.has_errors():
return render()
action(submit)
return request.redirect(exit_path)