# Converting form1 forms to use the form2 library

# Introduction

These are some notes and examples for converting Quixote form1 forms, that is forms derived from `quixote.form.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.

# Converting form1 forms using using the compatibility module

Here's the short list of things to do to convert form1 forms to form2 using compatibility.

> 1. Import the Form base class from `quixote.form2.compatibility` rather than from quixote.form.

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

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

> 4. 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.form2.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.form2.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.

# Converting form1 forms to form2 by functional rewrite

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

> 1. It determines if it's to create a new object or edit an existing one
> 2. It adds submit buttons and widgets
> 3. It has a function that knows how to render the form
> 4. It has a function that knows how to do error processing on the form
> 5. 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.

> 1. Get the value of any submit buttons using `form.get_submit`
> 2. If the form has not been submitted yet, return `render()`.
> 3. See if the cancel button was pressed, if so return a redirect.
> 4. 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.
> 5. 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.
> 6. If the form has not been submitted or if the form has errors, you simply want to render the form.
> 7. 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.
> 8. 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)