Merge pull request #497 from MongoEngine/string_fields

New model form generator: Support of StringField based fields

Author: insspb

docs/forms.md

@@ -1,4 +1,4 @@
-# Flask-WTF(WTForms) integration
+# WTForms integration
 
 ```{important}
 Documentation below is related to project version 2.0.0 or higher, old versions has
@@ -48,15 +48,21 @@ For all fields, processed by Flask-Mongoengine integration:
   {attr}`validators` extension by Flask-Mongoengine.
 - If model field definition have {attr}`wtf_filters` defined, they will be forwarded to
   WTForm as {attr}`filters`.
-- If model field definition have {attr}`required`, then {class}`~wtforms.validators.InputRequired`
-  will be added to form {attr}`validators`, otherwise {class}`~wtforms.validators.Optional`
+- If model field definition have {attr}`required`, then
+  {class}`~wtforms.validators.InputRequired`
+  will be added to form {attr}`validators`, otherwise
+  {class}`~wtforms.validators.Optional`
   added.
 - If model field definition have {attr}`verbose_name` it will be used as form field
   {attr}`label`, otherwise pure field name used.
 - If model field definition have {attr}`help_text` it will be used as form field
   {attr}`description`, otherwise empty string used.
-- Field's {attr}`default` used as form {attr}`default`, that's why for string fields
-  special {class}`~.NoneStringField` with `None` value support used.
+- Field's {attr}`default` used as form {attr}`default`, that's why special WTForms
+  fields implementations was created. Details can be found in
+  {mod}`flask_mongoengine.wtf.fields` module. In new form generator only 'Mongo'
+  prefixed classes are used for fields, other classes are deprecated and will be
+  removed in version **3.0.0**. If you have own nesting classes, you should check
+  inheritance and make an update.
 - Field's {attr}`choices`, if exist, used as form {attr}`choices`.
 
 ```{warning}
@@ -99,7 +105,53 @@ Not yet documented. Please help us with new pull request.
 
 ### EmailField
 
-Not yet documented. Please help us with new pull request.
+- API: {class}`.db_fields.EmailField`
+- Default form field class: {class}`~.MongoEmailField`
+
+#### Form generation behaviour
+
+Unlike [StringField] WTForm class of the field is not adjusted by normal form
+generation sequence and always match {class}`~.MongoEmailField`. All other
+adjustments, related to validators insert are work with EmailField in the same way,
+as in [StringField].
+
+Additional {class}`~wtforms.validators.Email` validator is also inserted to form
+field, to exclude unnecessary database request, if form data incorrect.
+
+Field respect user's adjustments in {attr}`wtf_field_class` option of
+{class}`.db_fields.EmailField`. This will change form field display, but will not
+change inserted validators.
+
+#### Examples
+
+strings_demo.py in example app contain basic non-requirement example. You can adjust
+it to any provided example for test purposes.
+
+##### Not required EmailField
+
+```python
+"""strings_demo.py"""
+from example_app.models import db
+
+
+class StringsDemoModel(db.Document):
+    """Documentation example model."""
+
+    url_field = db.EmailField()
+````
+
+##### Required EmailField
+
+```python
+"""strings_demo.py"""
+from example_app.models import db
+
+
+class StringsDemoModel(db.Document):
+    """Documentation example model."""
+
+    required_url_field = db.EmailField(required=True)
+````
 
 ### EmbeddedDocumentField
 
@@ -131,11 +183,215 @@ Not yet documented. Please help us with new pull request.
 
 ### StringField
 
-Not yet documented. Please help us with new pull request.
+- API: {class}`.db_fields.StringField`
+- Default form field class: Selected by field settings combination
+
+#### Form generation behaviour
+
+By default, during WTForm generation for fields without specified size (
+{attr}`min_length` or {attr}`max_length`) class {class}`.MongoTextAreaField` is used,
+in case when {attr}`min_length` or {attr}`max_length` set, then
+{class}`.MongoStringField` used and {class}`~wtforms.validators.Length` will be added
+to form field validators. This allows to keep documents of any size in mongodb.
+
+In some cases class {class}`~.MongoStringField` is not the best choice for field, even
+with limited size. In this case user can easily overwrite generated field class by
+providing {attr}`wtf_field_class` on {class}`.db_fields.StringField` field declaration,
+as on document, as well as on form generation steps.
+
+If database field definition has {attr}`regex` parameter set, then
+{class}`~wtforms.validators.Regexp` validator will be added to the form field.
+
+#### Features deprecated
+
+Field declaration step keyword arguments {attr}`password` and {attr}`textarea` are
+deprecated in Flask-Mongoengine version **2.0.0** and exist only to make migration
+steps easy.
+
+To implement same behaviour, user should use {attr}`wtf_field_class` setting on
+{class}`.db_fields.StringField` init.
+
+#### Related WTForm custom fields
+
+Several special WTForms field implementation was created to support mongodb database
+behaviour and do not create any values in database, in case of empty fields. They
+can be used as {attr}`wtf_field_class` setting or independently. Some of them used
+in another database fields too, but all of them based on
+{class}`wtforms.fields.StringField` and {class}`~.EmptyStringIsNoneMixin`. You can use
+{class}`~.EmptyStringIsNoneMixin` for own field types.
+
+- {class}`~.MongoEmailField`
+- {class}`~.MongoHiddenField`
+- {class}`~.MongoPasswordField`
+- {class}`~.MongoSearchField`
+- {class}`~.MongoStringField`
+- {class}`~.MongoTelField`
+- {class}`~.MongoTextAreaField`
+- {class}`~.MongoURLField`
+
+#### Examples
+
+strings_demo.py in example app contain basic non-requirement example. You can adjust
+it to any provided example for test purposes.
+
+##### Not limited StringField as MongoTextAreaField
+
+```python
+"""strings_demo.py"""
+from example_app.models import db
+
+
+class StringsDemoModel(db.Document):
+    """Documentation example model."""
+
+    string_field = db.StringField()
+```
+
+##### Not limited StringField as MongoTelField
+
+```python
+"""strings_demo.py"""
+from example_app.models import db
+from flask_mongoengine.wtf import fields as mongo_fields
+
+
+class StringsDemoModel(db.Document):
+    """Documentation example model."""
+
+    tel_field = db.StringField(wtf_field_class=mongo_fields.MongoTelField)
+```
+
+##### Not limited StringField as MongoTextAreaField with https regex
+
+[mongoengine] and [wtforms] projects are not consistent in how they work with regex.
+You will be safe, if you use {func}`re.compile` each time, when you work with regex
+settings, before parent projects itself.
+
+```python
+"""strings_demo.py"""
+import re
+
+from example_app.models import db
+
+
+class StringsDemoModel(db.Document):
+    """Documentation example model."""
+
+    regexp_string_field = db.StringField(regex=re.compile(
+        r"^(https:\/\/)[\w.-]+(?:\.[\w\.-]+)+[\w\-\._~:/?#[\]@!\$&'\(\)\*\+,;=]+$"
+    ))
+```
+
+##### Size limited StringField as MongoStringField
+
+```python
+"""strings_demo.py"""
+from example_app.models import db
+
+
+class StringsDemoModel(db.Document):
+    """Documentation example model."""
+
+    sized_string_field = db.StringField(min_length=5)
+```
+
+##### Required password field with minimum size
+
+```python
+"""strings_demo.py"""
+from example_app.models import db
+from flask_mongoengine.wtf import fields as mongo_fields
+
+
+class StringsDemoModel(db.Document):
+    """Documentation example model."""
+
+    password_field = db.StringField(
+        wtf_field_class=mongo_fields.MongoPasswordField,
+        required=True,
+        min_length=5,
+    )
+```
 
 ### URLField
 
-Not yet documented. Please help us with new pull request.
+- API: {class}`.db_fields.URLField`
+- Default form field class: {class}`~.MongoURLField`
+
+#### Form generation behaviour
+
+Unlike [StringField] WTForm class of the field is not adjusted by normal form
+generation sequence and always match {class}`~.MongoURLField`. All other
+adjustments, related to validators insert are work with EmailField in the same way,
+as in [StringField].
+
+Additional {class}`~wtforms.validators.Regexp` validator is also inserted to form
+field, to exclude unnecessary database request, if form data incorrect. This
+validator use regexp, provided in {attr}`url_regex` of {class}`.db_fields.URLField`,
+or default URL regexp from [mongoengine] project. This is different from
+Flask-Mongoengine version **1.0.0** or earlier, where {class}`~wtforms.validators.URL`
+was inserted. This was changed, to exclude validators conflicts.
+
+```{important}
+{func}`~.model_form` is still use {class}`~wtforms.validators.URL` for
+compatibility with old setups.
+```
+
+Field respect user's adjustments in {attr}`wtf_field_class` option of
+{class}`.db_fields.URLField`. This will change form field display, but will not
+change inserted validators.
+
+#### Examples
+
+strings_demo.py in example app contain basic non-requirement example. You can adjust
+it to any provided example for test purposes.
+
+##### Not required URLField
+
+```python
+"""strings_demo.py"""
+from example_app.models import db
+
+
+class StringsDemoModel(db.Document):
+    """Documentation example model."""
+
+    url_field = db.URLField()
+````
+
+##### Required URLField with minimum size
+
+```python
+"""strings_demo.py"""
+from example_app.models import db
+
+
+class StringsDemoModel(db.Document):
+    """Documentation example model."""
+
+    required_url_field = db.URLField(required=True, min_length=25)
+````
+
+##### URLField with https only regexp check, if data exist
+
+Regexp for {attr}`url_regex` should be prepared by {mod}`re`.
+
+```python
+"""strings_demo.py"""
+import re
+
+from example_app.models import db
+
+
+class StringsDemoModel(db.Document):
+    """Documentation example model."""
+
+    https_url_field = db.URLField(
+        url_regex=re.compile(
+            r"^(https:\/\/)[\w.-]+(?:\.[\w\.-]+)+[\w\-\._~:/?#[\]@!\$&'\(\)\*\+,;=]+$"
+        ),
+    )
+````
 
 ## Unsupported fields
 
@@ -234,7 +490,15 @@ Not yet documented. Please help us with new pull request.
 Not yet documented. Please help us with new pull request.
 
 [mongoengine]: https://docs.mongoengine.org/
+
 [supported fields]: #supported-fields
+
 [#379]: https://github.com/MongoEngine/flask-mongoengine/issues/379
+
 [integration]: forms
+
 [global transforms]: #global-transforms
+
+[stringfield]: #stringfield
+
+[wtforms]: https://wtforms.readthedocs.io/en/3.0.x/

example_app/app.py

@@ -4,6 +4,7 @@
 
 from example_app import views
 from example_app.models import db
+from example_app.strings_demo import strings_demo_view
 from flask_mongoengine.panels import mongo_command_logger
 
 app = flask.Flask("example_app")
@@ -40,6 +41,10 @@
 
 app.add_url_rule("/", view_func=views.index, methods=["GET", "POST"])
 app.add_url_rule("/pagination", view_func=views.pagination, methods=["GET", "POST"])
+app.add_url_rule("/strings_demo", view_func=strings_demo_view, methods=["GET", "POST"])
+app.add_url_rule(
+    "/strings_demo/<pk>/", view_func=strings_demo_view, methods=["GET", "POST"]
+)
 
 if __name__ == "__main__":
     app.run(host="0.0.0.0", port=8000)

example_app/strings_demo.py

@@ -0,0 +1,52 @@
+"""Strings and strings related fields demo model."""
+import re
+
+from flask import render_template, request
+
+from example_app.models import db
+from flask_mongoengine.wtf import fields as mongo_fields
+
+
+class StringsDemoModel(db.Document):
+    """Documentation example model."""
+
+    string_field = db.StringField()
+    regexp_string_field = db.StringField(
+        regex=re.compile(
+            r"^(https:\/\/)[\w.-]+(?:\.[\w\.-]+)+[\w\-\._~:/?#[\]@!\$&'\(\)\*\+,;=]+$"
+        )
+    )
+    sized_string_field = db.StringField(min_length=5)
+    tel_field = db.StringField(wtf_field_class=mongo_fields.MongoTelField)
+    password_field = db.StringField(
+        wtf_field_class=mongo_fields.MongoPasswordField,
+        required=True,
+        min_length=5,
+    )
+    email_field = db.EmailField()
+    url_field = db.URLField()
+
+
+StringsDemoForm = StringsDemoModel.to_wtf_form()
+
+
+def strings_demo_view(pk=None):
+    """Return all fields demonstration."""
+    form = StringsDemoForm()
+    obj = None
+    if pk:
+        obj = StringsDemoModel.objects.get(pk=pk)
+        form = StringsDemoForm(obj=obj)
+
+    if request.method == "POST" and form.validate_on_submit():
+        if pk:
+            form.populate_obj(obj)
+            obj.save()
+        else:
+            form.save()
+    page_num = int(request.args.get("page") or 1)
+    page = StringsDemoModel.objects.paginate(page=page_num, per_page=100)
+
+    return render_template(
+        "strings_demo.html", page=page, form=form, model=StringsDemoModel
+    )