1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
|
Widgets
=======
Widgets are classes whose purpose are to render a field to its usable
representation, usually XHTML. When a field is called, the default behaviour
is to delegate the rendering to its widget. This abstraction is provided so
that widgets can easily be created to customize the rendering of existing
fields.
**Note** All built-in widgets will return upon rendering a "HTML-safe" unicode
string subclass that many templating frameworks (Jinja, Mako, Genshi) will
recognize as not needing to be auto-escaped.
Built-in widgets
----------------
.. autoclass:: wtforms.widgets.ColorInput
.. autoclass:: wtforms.widgets.CheckboxInput
.. autoclass:: wtforms.widgets.DateTimeInput
.. autoclass:: wtforms.widgets.DateTimeLocalInput
.. autoclass:: wtforms.widgets.DateInput
.. autoclass:: wtforms.widgets.EmailInput
.. autoclass:: wtforms.widgets.FileInput
.. autoclass:: wtforms.widgets.HiddenInput
.. autoclass:: wtforms.widgets.Input
.. autoclass:: wtforms.widgets.ListWidget
.. autoclass:: wtforms.widgets.MonthInput
.. autoclass:: wtforms.widgets.NumberInput
.. autoclass:: wtforms.widgets.PasswordInput
.. autoclass:: wtforms.widgets.RadioInput
.. autoclass:: wtforms.widgets.RangeInput
.. autoclass:: wtforms.widgets.SubmitInput
.. autoclass:: wtforms.widgets.SearchInput
.. autoclass:: wtforms.widgets.Select
.. autoclass:: wtforms.widgets.TableWidget
.. autoclass:: wtforms.widgets.TelInput
.. autoclass:: wtforms.widgets.TextArea
.. autoclass:: wtforms.widgets.TextInput
.. autoclass:: wtforms.widgets.TimeInput
.. autoclass:: wtforms.widgets.URLInput
.. autoclass:: wtforms.widgets.WeekInput
Widget-Building Utilities
-------------------------
These utilities are used in WTForms widgets to help render HTML and also in
order to work along with HTML templating frameworks. They can be imported for
use in building custom widgets as well.
.. autofunction:: wtforms.widgets.html_params
WTForms uses `MarkupSafe`_ to escape unsafe HTML characters before
rendering. You can mark a string using :class:`markupsafe.Markup` to
indicate that it should not be escaped.
.. _MarkupSafe: https://markupsafe.palletsprojects.com/
Custom widgets
--------------
Widgets, much like validators, provide a simple callable contract. Widgets can
take customization arguments through a constructor if needed as well. When
the field is called or printed, it will call the widget with itself as the
first argument and then any additional arguments passed to its caller as
keywords. Passing the field is done so that one instance of a widget might be
used across many field instances.
Let's look at a widget which renders a text field with an additional class if
there are errors::
class MyTextInput(TextInput):
def __init__(self, error_class='has_errors'):
super(MyTextInput, self).__init__()
self.error_class = error_class
def __call__(self, field, **kwargs):
if field.errors:
c = kwargs.pop('class', '') or kwargs.pop('class_', '')
kwargs['class'] = '%s %s' % (self.error_class, c)
return super(MyTextInput, self).__call__(field, **kwargs)
In the above example, we extended the behavior of the existing
:class:`TextInput` widget to append a CSS class as needed. However, widgets
need not extend from an existing widget, and indeed don't even have to be a
class. For example, here is a widget that renders a
:class:`~wtforms.fields.SelectMultipleField` as a collection of checkboxes::
def select_multi_checkbox(field, ul_class='', **kwargs):
kwargs.setdefault('type', 'checkbox')
field_id = kwargs.pop('id', field.id)
html = ['<ul %s>' % html_params(id=field_id, class_=ul_class)]
for value, label, checked, render_kw in field.iter_choices():
choice_id = '%s-%s' % (field_id, value)
options = dict(kwargs, name=field.name, value=value, id=choice_id)
if checked:
options['checked'] = 'checked'
html.append('<li><input %s /> ' % html_params(**options))
html.append('<label for="%s">%s</label></li>' % (choice_id, label))
html.append('</ul>')
return ''.join(html)
class TestForm(Form):
tester = SelectMultipleField(choices=my_choices, widget=select_multi_checkbox)
|
