Ferris provides HTML form support using the wtforms library. Please consult the wtforms documentation for a list of field types and advanced form usage. This documentation covers how to use wtforms in conjuction with Ferris.
Usually you’ll be using forms to interact with model data. 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():
Creates and returns a dynamic wtforms.Form class for a given ndb.Model class. The form class can be used as it is or serve as a base for extended form classes, which can then mix non-model related fields, subforms with other model forms, among other possibilities.
Parameters: |
|
---|
For example:
CatInfoForm = model_form(Cat)
This is exactly what Scaffolding does if you do not explicitly 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()
Tip
All of the standard arguments to model_form work, including only, exclude, and most importantly field_args. Check out the associated documentation for wtforms.
When using Scaffolding, you can specify the Model Form to use by setting Scaffold.ModelForm or self.scaffold.ModelForm.
For example:
def Cats(Controller):
class Meta:
...
Class Scaffold:
ModelForm = CatInfoForm
or:
def add(self):
self.scaffold.ModelForm = CatInfoForm
return scaffold.add(self)
Once you have a form class, you can process form data into your form using Request Parsers.
For example:
def contact_us(self):
form = ContactUsForm()
self.parse_request(container=form)
if self.request.method != 'GET' and form.validate():
return form.message
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:
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_field(form, form.title)}}
{{f.form_field(form, form.description)}}
</form>