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
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
Usage
=====
Forms
`````
Floppyforms are supposed to work just like Django forms::
import floppyforms as forms
class ProfileForm(forms.Form):
name = forms.CharField()
email = forms.EmailField()
url = forms.URLField()
With some template code:
.. code-block:: jinja
<form method="post" action="/some-action/">
{% csrf_token %}
{{ form.as_p }}
<p><input type="submit" value="Yay!"></p>
</form>
The form will be rendered using the ``floppyforms/layouts/p.html`` template.
See the :doc:`documentation about layouts <layouts>` for details.
Each field has a default widget and widgets are rendered using templates.
Default templates are provided and their output is relatively similar to
Django widgets, with a few :doc:`minor differences</differences>`:
* HTML5 ``<input>`` types are supported: ``url``, ``email``, ``date``,
``datetime``, ``time``, ``number``, ``range``, ``search``, ``color``,
``tel``.
* The ``required`` and ``placeholder`` attributes are also supported.
Widgets are rendered with the following context variables:
* ``hidden``: set to ``True`` if the field is hidden.
* ``required``: set to ``True`` if the field is required.
* ``type``: the input type. Can be ``text``, ``password``, etc. etc.
* ``name``: the name of the input.
* ``attrs``: the dictionnary passed as a keyword argument to the widget. It
contains the ``id`` attribute of the widget by default.
Each widget has a ``template_name`` attribute which points to the template to
use when rendering the widget. A basic template for an ``<input>`` widget may
look like:
.. code-block:: jinja
<input {% for key, val in attrs.items %}
{{ key }}="{{ val }}"
{% endfor %}
type="{{ type }}"
name="{{ name }}"
{% if value %}value="{{ value }}"{% endif %}>
The default floppyforms template for an ``<input>`` widget is slightly more
complex.
Some widgets may provide extra context variables and extra attributes:
====================== ====================================== ==============
Widget Extra context Extra ``attrs``
====================== ====================================== ==============
Textarea ``rows``, ``cols``
NumberInput ``min``, ``max``, ``step``
RangeInput ``min``, ``max``, ``step``
Select ``optgroups``, ``multiple``
RadioSelect ``optgroups``, ``multiple``
NullBooleanSelect ``optgroups``, ``multiple``
SelectMultiple ``optgroups``, ``multiple`` (``True``)
CheckboxSelectMultiple ``optgroups``, ``multiple`` (``True``)
====================== ====================================== ==============
Furthermore, you can specify custom ``attrs`` during widget definition. For
instance, with a field created this way::
bar = forms.EmailField(widget=forms.EmailInput(attrs={'placeholder': 'john@example.com'}))
Then the ``placeholder`` variable is available in the ``attrs`` template
variable.
.. _usage-modelforms:
ModelForms
``````````
You can use ``ModelForms`` with floppyforms as you would use a ordinary django
``ModelForm``. Here is an example showing it for a basic ``Profile`` model::
class Profile(models.Model):
name = models.CharField(max_length=255)
url = models.URLField()
Now create a ``ModelForm`` using floppyforms::
import floppyforms.__future__ as forms
class ProfileForm(forms.ModelForm):
class Meta:
model = Profile
fields = ('name', 'url')
The ``ProfileForm`` will now have form fields for all the model fields. So
there will be a ``floppyforms.CharField`` used for the ``Profile.name`` model
field and a ``floppyforms.URLField`` for ``Profile.url``.
.. note::
Please note that you have to import from ``floppyforms.__future__`` to use
this feature. Here is why:
This behaviour changed in version 1.2 of **django-floppyforms**. Before,
no alterations were made to the widgets of a ``ModelForm``. So you had to
take care of assigning the floppyforms widgets to the django form fields
yourself to use the template based rendering provided by floppyforms. Here
is an example of how you would have done it with django-floppyforms 1.1
and earlier::
import floppyforms as forms
class ProfileForm(forms.ModelForm):
class Meta:
model = Profile
fields = ('name', 'url')
widgets = {
'name': forms.TextInput,
'url': forms.URLInput,
}
Since the change is backwards incompatible, we decided to provide a
deprecation path. If you create a ``ModelForm`` with django-floppyforms
1.2 and use ``import floppyforms as forms`` as the import you will get the
old behaviour and you will see a ``DeprecationWarning``.
To use the new behaviour, you can use ``import floppyforms.__future__ as
forms`` as the import.
Please make sure to test your code if your modelforms work still as
expected with the new behaviour. The old version's behaviour will be
removed completely with django-floppyforms 1.3.
|
