Forms

Ferris uses the excellent wtforms library. Please consult the wtforms documentation for a list of field types and advanced form usage. We will cover how to use forms in conjuction with Ferris.

Using Forms in Handlers

Once you have a form class, you can process form data into your form using the process_form_data function:

Handler.process_form_data(form, obj=None)

Processes POST and JSON data and provides it to the given form.

If obj is specified, that’s used as the fallback data for the form is nothing was submitted.

For example:

def contact_us(self):
    form = ContactUsForm()
    self.process_form_data(form)

    if self.request.method != 'GET' and form.validate():
        return form.message

Using Forms in Views

Since Ferris uses Jinja2 and wtforms, all of the same principles in the wtforms documentation apply.

Ferris does however provide one useful macro in macros/form.html:

ferris.core.forms.form_control(field, container_element='div')

Generates a bootstrap style form control with error message and help block.

For example:

{% import "macros/form.html" as f with context %}

<form>
    {{f.form_control(form.title)}}
    {{f.form_control(form.description)}}
</form>

Model Form

Usually you’ll be using forms to interact with model data. In Ferris, this sort of use is called a Model Form, a model can have any number of forms (for example, different forms for different workflow steps).

You can generate a model form automatically using model_form:

ferris.core.forms.model_form(model, *args, **kwargs)

Generates a Form class automatically from a Model class. For more information an the full list of arguments, see the wtforms documentation.

For example:

CatInfoForm = model_form(Cat)

This is exactly what Scaffolding does if you do not specify a model form.

You can also add additional fields to your form just like any other form:

class CatInfoForm(model_form(Cat)):
    claws = wtforms.fields.BooleanField()

When using Scaffolding, you can specify the Model Form to use by setting ModelForm.

For example:

@scaffold
def Cats(Handler):
    ModelForm = CatInfoForm

or:

def add(self):
    self.ModelForm = CatInfoForm
    return self.scaffold.add(self)