Contents:¶

Common Library¶

Bootstrap¶

default_widgets¶

A dictionary defining the default widget type for each kind of WTForms Field.

Very useful when using FieldRenderer to automatically render your fields without declaring widget=MyWidget().

Core¶

HTML5¶

Extras¶

Util¶

Abstract Widgets¶

Extending¶

Making Widgets For Your Favourite Framework¶

Create a submodule within this module named the title of the web framework you wish to bring functionality to.

When creating widgets from scratch, be sure to apply the wtforms_webwidgets.common.CustomWidgetMixin mixin to your class.

If you are extending an existing wtforms.widgets class, decorate it with wtforms_webwidgets.common.custom_widget_wrapper. This allows our FieldRenderer know this is a custom widget, and not to check the lookup dictionary to render a field which has this widget.

Contibuting¶

To contribute your improvements to this library, please fork the repository, add functionality and submit a pull request.

Usage In Flask (And Others)¶

When declaring fields as part of a form using WTForms, if you wished to set a custom widget for a field, you would need to set widget=MyWidget().

I have found when overriding all widgets with some skinned widgets, it’s very tedious and prone to errors to set this value every time. Instead, it is more intuitive to set a dictionary of defaults, and look up field types and get their apropriate widget.

To use this method we need:

A way of identifying when a widget has been set from the Field kwargs.

A way of overriding a default widget when it is not provided.

I have found that it is most aproriatly done within a render_field templating macro.

Provided within the common submodule of this framework is the class FieldRenderer. This class provides an interface for setting a lookup table for default renderers and a method to render a given field.

Example¶

An example from Flask/Jinja.

from wtforms_webwidgets import FieldRenderer
from wtforms_webwidgets.bootstrap import default_widgets

renderer = FieldRenderer(lookup_dict=default_widgets)

# Alternatively, you can declare your own lookup dictionary:
import wtforms_webwidgets.bootstrap as wt_bs
renderer = FieldRenderer(lookup_dict={
    'TextField': wt_bs.TextInput(),
})

# Example for injecting into Jinja within Flask
app.jinja_env.globals['render_field'] = renderer

Now, within your templates you can do the following:

{{ render_field(form.my_field) }}

If the widget was not declared with a custom widget, it will be renderered accordingly to the FieldRender’s lookup dictionary.