Skip to content

Latest commit

 

History

History
145 lines (106 loc) · 5.56 KB

README.md

File metadata and controls

145 lines (106 loc) · 5.56 KB
Raw

WTForms HTML5

PyPI Status Coverage Status pre-commit.ci Status Test Status

VERSION: 0.6.1

WTForms HTML5 generates render keywords for HTML5 INPUT widgets used by the WTForms library.

Evolution

Original Function: This module used to add support for the new HTML5 INPUT elements to WTForms. Besides supporting the new INPUT types, it also set some of the new attributes automatically, based on widget type and what kind of validators where set for the field.

Changes: WTForms — beginning around version 1.0.4 — started to implement some of these features. As of late 2016 the development version — that should become version 3 — has enough support for them IMO, so that to prevent the duplication of functionality, WTForms HTML5 dropped all the fields, widgets and validators — just use vanilla WTForms.

Current Function: starting with 0.2 versions of WTForms HTML5 merely contain one function: get_html5_kwargs — it adds the automatically generated keys to the render keywords of a WTForms field. A slim subclass of the new default Meta class for forms is also provided: AutoAttrMeta. If you use this class as your forms Meta, you get the automatic attributes for all fields in your form, just like in the original version of WTForms HTML5.

Supported Auto–Attributes

  • required

    Is set if the field has the required flag set. This happens i.e. if you use the DataRequired or InputRequired validator. The required attribute is used by browsers to indicate a required field (and most browsers won't activate the forms action unless all required fields have content).

  • invalid

    If the field got any validation errors, the CSS class invalid is added. The invalid class is also set by browsers, if they detect errors on a field. The validation errors detected by your code, are then by default styled in the same way as browser generated errors.

  • min / max and minlength / maxlength

    If either Length or NumberRange is used as a validator to set minimal and / or maximal values, the corresponding INPUT attribute is set (based on which validator is used). This allows for browser based validation of the values.

  • title

    If no title is provided for a field, the description (if one is set) is used for the title attribute.

Example

Declare your form just like in vanilla WTForms, but include AutoAttrMeta as your meta class:

>>> from wtforms import Form, StringField
>>> from wtforms.validators import InputRequired, Length
>>> from wtforms_html5 import AutoAttrMeta
>>> class MyForm(Form):
...   class Meta(AutoAttrMeta):
...     pass
...   test_field = StringField(
...     'Testfield',
...      validators=[InputRequired(), Length(min=3, max=12)],
...      description='Just a test field.',
...   )
>>> form = MyForm()

The only difference is, that you include a Meta class, that inherits from AutoAttrMeta.

This meta class sets the above mentioned attributes automatically for all the fields of the form:

>>> form.test_field()
'<input id="test_field" maxlength="12" minlength="3" name="test_field" required title="Just a test field." type="text" value="">'

The minlength and maxlength attributes are created because the Length validator was used. And the field is marked required because of the InputRequired validator. The field also gets a title taken from the fields description.

If you validate the form and any errors pop up, the field also get invalid added to its class:

>>> form.validate()
False
>>> form.test_field()
'<input class="invalid" id="test_field" maxlength="12" minlength="3" name="test_field" required title="Just a test field." type="text" value="">'

Install

You can install WTForms HTML5 with pip or from source.

pip is "a tool for installing and managing Python packages". If you don't have it installed, see the pip install instructions.

pip install --user wtforms-html5

Install Requirements

Since WTForms HTML5 only adds functionality to WTForms, you need to have it installed too. But if you use the installation method described above, it should have been taken care of.

Testing and Contribution

WTForms HTML5 is at home at: https://github.com/brutus/wtforms-html5/

You can run make setup after checkout, to setup a development environment.

If you find any bugs, issues or anything, please use the issue tracker.

Testing

You can run the provided doctest like this: make doctest. If you want to run the test cases, run make unittest (or make coverage). You can also run make all-tests to run this for all supported versions (this might take some time though).

If something fails, please get in touch.