Skip to content

Commit f71aba0

Browse files
insspbinsspb
authored
Merge pull request #483 from MongoEngine/forms-update
Added: New Forms and Fields generation approach
2 parents 863e00f + b73b18f commit f71aba0

16 files changed

+1753
-187
lines changed

‎docs/api/base.rst

+16
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,22 @@ flask_mongoengine.connection module
88

99
.. automodule:: flask_mongoengine.connection
1010

11+
flask_mongoengine.db_fields module
12+
----------------------------------
13+
14+
.. automodule:: flask_mongoengine.db_fields
15+
:special-members: __init__
16+
17+
flask_mongoengine.decorators module
18+
-----------------------------------
19+
20+
.. automodule:: flask_mongoengine.decorators
21+
22+
flask_mongoengine.documents module
23+
----------------------------------
24+
25+
.. automodule:: flask_mongoengine.documents
26+
1127
flask_mongoengine.json module
1228
-----------------------------
1329

‎docs/api/wtf.rst

-5
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,6 @@ WTF module API
33

44
This is the flask_mongoengine.wtf modules API documentation.
55

6-
flask_mongoengine.wtf.db_fields module
7-
--------------------------------------
8-
9-
.. automodule:: flask_mongoengine.wtf.db_fields
10-
116
flask_mongoengine.wtf.fields module
127
-----------------------------------
138

‎docs/db_model.md

+47
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Database model and fields definition
2+
3+
```{important}
4+
Flask-Mongoengine does not adjust database level behaviour of [mongoengine] fields
5+
definition, except [keyword only definition] requirement. Everything other on
6+
database level match [mongoengine] project. All parent methods, arguments (as
7+
keyword arguments) and keyword arguments are supported.
8+
9+
If you are not intend to use WTForms integration, you are free to use fields classes
10+
from parent [mongoengine] project; this should not break anything.
11+
```
12+
13+
## Supported fields
14+
15+
Flask-Mongoengine support all **database** fields definition. Even if there will be some
16+
new field type created in parent [mongoengine] project, we will silently bypass
17+
field definition to it, if we do not declare rules on our side.
18+
19+
```{note}
20+
Version **2.0.0** Flask-Mongoengine update support [mongoengine] fields, based on
21+
version **mongoengine==0.21**. Any new fields bypassed without modification.
22+
```
23+
24+
## Keyword only definition
25+
26+
```{eval-rst}
27+
.. versionchanged:: 2.0.0
28+
```
29+
30+
Database model definition rules and Flask-WTF/WTForms [integration] was seriously
31+
updated in version **2.0.0**. Unfortunately, these changes implemented without any
32+
deprecation stages.
33+
34+
Before version **2.0.0** Flask-Mongoengine integration allowed to pass fields
35+
parameters as arguments. To exclude any side effects or keyword parameters
36+
duplication/conflicts, since version **2.0.0** all fields require keyword
37+
only setup.
38+
39+
Such approach removes number of issues and questions, when users frequently used
40+
Flask-WTF/WTForms definition rules by mistake, or just missed that some arguments
41+
was passed to keyword places silently creating unexpected side effects. You can
42+
check issue [#379] as example of one of such cases.
43+
44+
[mongoengine]: https://docs.mongoengine.org/
45+
[#379]: https://github.com/MongoEngine/flask-mongoengine/issues/379
46+
[integration]: forms
47+
[keyword only definition]: #keyword-only-definition

‎docs/forms.md

+240
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
# Flask-WTF(WTForms) integration
2+
3+
```{important}
4+
Documentation below is related to project version 2.0.0 or higher, old versions has
5+
completely different approach for forms generation.
6+
7+
And despite the fact that the old code is included in version 2.0.0 to keep correct
8+
deprecation workflow (where possible), it is not documented (and was not) and not
9+
maintained.
10+
11+
If you faced any forms problems, consider migration to new methods and approach.
12+
```
13+
14+
Flask-Mongoengine and Flask-WTF/WTForms are heavily integrated, to reduce amount of
15+
boilerplate code, required to make database model and online form. In the same time
16+
a lot of options was created to keep extreme flexibility.
17+
18+
After database model definition user does not require to repeat same code in form
19+
definition, instead it is possible to use integrated converter, that will do most of
20+
the work.
21+
22+
Flask-Mongoengine will transform some model's properties to Flask-WTF/WTForms
23+
validators, so user does not need to care about standards. For full list of
24+
transformations, please review [global transforms] and specific field documentation
25+
below.
26+
27+
In the same time, user is able to adjust database fields definition with
28+
specific settings as on stage of Document model definition, as on form generation stage.
29+
This allows to create several forms for same model, for different circumstances.
30+
31+
## Requirements
32+
33+
For correct integration behavior several requirements should be met:
34+
35+
- Document classes should be used from Flask-Mongoengine
36+
{class}`flask_mongoengine.MongoEngine` class, or from
37+
{mod}`flask_mongoengine.documents` module.
38+
- Document classes should be used from Flask-Mongoengine
39+
{class}`flask_mongoengine.MongoEngine` class, or from
40+
{mod}`flask_mongoengine.db_fields` module.
41+
42+
## Global transforms
43+
44+
For all fields, processed by Flask-Mongoengine integration:
45+
46+
- If model field definition have {attr}`wtf_validators` defined, they will be
47+
forwarded to WTForm as {attr}`validators`. This is not protection from
48+
{attr}`validators` extension by Flask-Mongoengine.
49+
- If model field definition have {attr}`wtf_filters` defined, they will be forwarded to
50+
WTForm as {attr}`filters`.
51+
- If model field definition have {attr}`required`, then {class}`~wtforms.validators.InputRequired`
52+
will be added to form {attr}`validators`, otherwise {class}`~wtforms.validators.Optional`
53+
added.
54+
- If model field definition have {attr}`verbose_name` it will be used as form field
55+
{attr}`label`, otherwise pure field name used.
56+
- If model field definition have {attr}`help_text` it will be used as form field
57+
{attr}`description`, otherwise empty string used.
58+
- Field's {attr}`default` used as form {attr}`default`, that's why for string fields
59+
special {class}`~.NoneStringField` with `None` value support used.
60+
- Field's {attr}`choices`, if exist, used as form {attr}`choices`.
61+
62+
```{warning}
63+
As at version **2.0.0** there is no {attr}`wtf_validators` duplicates/conflicts check.
64+
User should be careful with manual {attr}`wtf_validators` setup. And in case of forms
65+
problems this is first place to look on.
66+
67+
{attr}`wtf_validators` and {attr}`wtf_filters` duplication check expected in future
68+
versions; PRs are welcome.
69+
```
70+
71+
Some additional transformations are made by specific field, check exact field
72+
documentation below for more info.
73+
74+
## Supported fields
75+
76+
### BinaryField
77+
78+
Not yet documented. Please help us with new pull request.
79+
80+
### BooleanField
81+
82+
Not yet documented. Please help us with new pull request.
83+
84+
### DateField
85+
86+
Not yet documented. Please help us with new pull request.
87+
88+
### DateTimeField
89+
90+
Not yet documented. Please help us with new pull request.
91+
92+
### DecimalField
93+
94+
Not yet documented. Please help us with new pull request.
95+
96+
### DictField
97+
98+
Not yet documented. Please help us with new pull request.
99+
100+
### EmailField
101+
102+
Not yet documented. Please help us with new pull request.
103+
104+
### EmbeddedDocumentField
105+
106+
Not yet documented. Please help us with new pull request.
107+
108+
### FileField
109+
110+
Not yet documented. Please help us with new pull request.
111+
112+
### FloatField
113+
114+
Not yet documented. Please help us with new pull request.
115+
116+
### IntField
117+
118+
Not yet documented. Please help us with new pull request.
119+
120+
### ListField
121+
122+
Not yet documented. Please help us with new pull request.
123+
124+
### ReferenceField
125+
126+
Not yet documented. Please help us with new pull request.
127+
128+
### SortedListField (partly?)
129+
130+
Not yet documented. Please help us with new pull request.
131+
132+
### StringField
133+
134+
Not yet documented. Please help us with new pull request.
135+
136+
### URLField
137+
138+
Not yet documented. Please help us with new pull request.
139+
140+
## Unsupported fields
141+
142+
### CachedReferenceField
143+
144+
Not yet documented. Please help us with new pull request.
145+
146+
### ComplexDateTimeField
147+
148+
Not yet documented. Please help us with new pull request.
149+
150+
### DynamicField
151+
152+
Not yet documented. Please help us with new pull request.
153+
154+
### EmbeddedDocumentListField
155+
156+
Not yet documented. Please help us with new pull request.
157+
158+
### EnumField
159+
160+
Not yet documented. Please help us with new pull request.
161+
162+
### GenericEmbeddedDocumentField
163+
164+
Not yet documented. Please help us with new pull request.
165+
166+
### GenericLazyReferenceField
167+
168+
Not yet documented. Please help us with new pull request.
169+
170+
### GeoJsonBaseField
171+
172+
Not yet documented. Please help us with new pull request.
173+
174+
### GeoPointField
175+
176+
Not yet documented. Please help us with new pull request.
177+
178+
### ImageField
179+
180+
Not yet documented. Please help us with new pull request.
181+
182+
### LazyReferenceField
183+
184+
Not yet documented. Please help us with new pull request.
185+
186+
### LineStringField
187+
188+
Not yet documented. Please help us with new pull request.
189+
190+
### LongField
191+
192+
Not yet documented. Please help us with new pull request.
193+
194+
### MapField
195+
196+
Not yet documented. Please help us with new pull request.
197+
198+
### MultiLineStringField
199+
200+
Not yet documented. Please help us with new pull request.
201+
202+
### MultiPointField
203+
204+
Not yet documented. Please help us with new pull request.
205+
206+
### MultiPolygonField
207+
208+
Not yet documented. Please help us with new pull request.
209+
210+
### PointField
211+
212+
Not yet documented. Please help us with new pull request.
213+
214+
### PolygonField
215+
216+
Not yet documented. Please help us with new pull request.
217+
218+
### SequenceField
219+
220+
Not yet documented. Please help us with new pull request.
221+
222+
### UUIDField
223+
224+
Not yet documented. Please help us with new pull request.
225+
226+
## Unsure
227+
228+
### GenericReferenceField
229+
230+
Not yet documented. Please help us with new pull request.
231+
232+
### ObjectIdField
233+
234+
Not yet documented. Please help us with new pull request.
235+
236+
[mongoengine]: https://docs.mongoengine.org/
237+
[supported fields]: #supported-fields
238+
[#379]: https://github.com/MongoEngine/flask-mongoengine/issues/379
239+
[integration]: forms
240+
[global transforms]: #global-transforms

‎docs/index.rst

+3
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,9 @@ You can also use `WTForms <http://wtforms.simplecodes.com/>`_ as model forms for
1111
:maxdepth: 2
1212

1313
flask_config
14+
db_model
15+
forms
16+
migration_to_v2
1417
custom_queryset
1518
wtf_forms
1619
session_interface

0 commit comments

Comments
 (0)