WTForms extension

Offers integration with WTForms.

status:beta dependencies:wtforms

The extension provides two new field classes: QuerySetSelectField and DocumentSelectField (inspired by wtforms.ext.django.*). They connect the forms with the Doqu API for queries. You can manually create forms with these fields.

The easiest way to create a Document-compliant form is using the function document_form_factory(). It returns a form class based on the document structure:

from doqu import Document
from doqu import validators
from doqu.ext.forms import document_form_factory

class Location(Document):
    structure = {'name': unicode}

class Person(Document):
    structure = {'name': unicode, 'age': int, 'location': Location}
    labels = {'name': 'Full name', 'age': 'Age', 'location': 'Location'}
    validators = {'name': [required()]}

PersonForm = document_form_factory(Person)

The last line does the same as this code:

from wtforms import TextField, IntegerField, validators
from doqu.ext.forms import DocumentSelectField

class PersonForm(wtforms.Form):
    name = TextField('Full name', [validators.Required()])
    age = IntegerField('Age')
    location = DocumentSelectField('Location', [], Location)

Warning

currently only validators Required and Optional are translated to the form validators; in the future most of them can be translated automatically.

doqu.ext.forms.document_form_factory(document_class, storage=None)

Expects a Document instance, creates and returns a wtforms.Form class for this model.

The form fields are selected depending on the Python type declared by each property.

Parameters:

• document_class – the Doqu document class for which the form should be created
• storage – a Docu-compatible storage; we need it to generate lists of choices for references to other models. If not defined, references will not appear in the form.

Caveat: the unicode type can be mapped to TextField and TextAreaField. It is impossible to guess which one should be used unless maximum length is defined for the property. TextAreaField is picked by default. It is a good idea to automatically shrink it with JavaScript so that its size always matches the contents.

class doqu.ext.forms.QuerySetSelectField(label=u'', validators=None, queryset=None, label_attr='', allow_blank=False, blank_text=u'', **kw)

Given a QuerySet either at initialization or inside a view, will display a select drop-down field of choices. The data property actually will store/keep an ORM model instance, not the ID. Submitting a choice which is not in the queryset will result in a validation error.

Specifying label_attr in the constructor will use that property of the model instance for display in the list, else the model object’s __str__ or __unicode__ will be used.

If allow_blank is set to True, then a blank choice will be added to the top of the list. Selecting this choice will result in the data property being None. The label for the blank choice can be set by specifying the blank_text parameter.

populate_obj(obj, name)

Populates obj.<name> with the field’s data.

Note :This is a destructive operation. If obj.<name> already exists, it will be overridden. Use with caution.

post_validate(form, validation_stopped)

Override if you need to run any field-level validation tasks after normal validation. This shouldn’t be needed in most cases.

Parameters:

• form – The form the field belongs to.
• validation_stopped – True if any validator raised StopValidation.

process(formdata, data=<object object at 0x7fdf3a327b40>)

Process incoming data, calling process_data, process_formdata as needed, and run filters.

If data is not provided, process_data will be called on the field’s default.

Field subclasses usually won’t override this, instead overriding the process_formdata and process_data methods. Only override this for special advanced processing, such as when a field encapsulates many inputs.

process_data(value)

Process the Python data applied to this field and store the result.

This will be called during form construction by the form’s kwargs or obj argument.

Parameters:

• value – The python object containing the value to process.

validate(form, extra_validators=())

Validates the field and returns True or False. self.errors will contain any errors raised during validation. This is usually only called by Form.validate.

Subfields shouldn’t override this, but rather override either pre_validate, post_validate or both, depending on needs.

Parameters:

• form – The form the field belongs to.
• extra_validators – A list of extra validators to run.

class doqu.ext.forms.DocumentSelectField(label=u'', validators=None, document_class=None, storage=None, **kw)

Like a QuerySetSelectField, except takes a document class instead of a queryset and lists everything in it.

populate_obj(obj, name)

Populates obj.<name> with the field’s data.

Note :This is a destructive operation. If obj.<name> already exists, it will be overridden. Use with caution.

post_validate(form, validation_stopped)

Override if you need to run any field-level validation tasks after normal validation. This shouldn’t be needed in most cases.

Parameters:

• form – The form the field belongs to.
• validation_stopped – True if any validator raised StopValidation.

process(formdata, data=<object object at 0x7fdf3a327b40>)

Process incoming data, calling process_data, process_formdata as needed, and run filters.

If data is not provided, process_data will be called on the field’s default.

Field subclasses usually won’t override this, instead overriding the process_formdata and process_data methods. Only override this for special advanced processing, such as when a field encapsulates many inputs.

process_data(value)

Process the Python data applied to this field and store the result.

This will be called during form construction by the form’s kwargs or obj argument.

Parameters:

• value – The python object containing the value to process.

validate(form, extra_validators=())

Validates the field and returns True or False. self.errors will contain any errors raised during validation. This is usually only called by Form.validate.

Subfields shouldn’t override this, but rather override either pre_validate, post_validate or both, depending on needs.

Parameters:

• form – The form the field belongs to.
• extra_validators – A list of extra validators to run.