HTML5 widgets for WTForms
Python Makefile

README.md

WTForms HTML5

Build Status Coverage Status Code Health

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. The current (late 2016) 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: recent versions of WTForms HTML5 (starting with 0.2) contain a 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. This validation errors detected by your code, are by default styled in the same way as browser generated errors.

  • min and max

    If either Length or NumberRange is used as a validator to set minimal and / or maximal values, the corresponding min / max INPUT attribute is set. 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" max="12" min="3" name="test_field" required title="Just a test field." type="text" value="">'

The min and max 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" max="12" min="3" name="test_field" required title="Just a test field." type="text" value="">'

Install

You can install WTForms HTML5 with pip or from source.

Install with pip

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

pip install wtforms-html5

Install from source

You can fetch the latest sourceball from github and unpack it, or just clone this repository:

git clone git://github.com/brutus/wtforms-html5.git

If you got the source, change into the directory and use setup.py:

python setup.py install

Install Requirements

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

Testing and Contribution

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

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

Testing

There are some doctest in the module. You can run them from the source directory like this: python -m doctest wtforms_html5.py. If you want to run the test cases, run python -m unittest discover (also from the source directory).

If something fails, please get in touch.

Testing Requirements

To run the test cases a few additional requirements need to be fulfilled. You can install all testing requirements like this: pip install -r requirements/testing.txt.