Merge pull request #510 from MongoEngine/dict_field

New model form generator: Support of DictField

Author: insspb

docs/api/wtf.rst

@@ -7,6 +7,7 @@ flask_mongoengine.wtf.fields module
 -----------------------------------
 
 .. automodule:: flask_mongoengine.wtf.fields
+   :special-members: __init__
 
 flask_mongoengine.wtf.models module
 -----------------------------------

docs/forms.md

@@ -147,7 +147,7 @@ class BooleanDemoModel(db.Document):
 
 Such definition will create document field, even if nothing selected. The value will
 be `None`. If, during edit, `yes` or `no` dropdown values replaced to `---`, then
-saved value in document will be aslo changed to `None`.
+saved value in document will be also changed to `None`.
 
 By default, `None` value represented as `---` text in dropdown.
 
@@ -407,7 +407,162 @@ class NumbersDemoModel(db.Document):
 
 ## DictField
 
-Not yet documented. Please help us with new pull request.
+- API: {class}`.db_fields.DictField`
+- Default form field class: {class}`~.MongoDictField`
+
+DictField has `Object` type in terms of Mongo database itself, so basically it defines
+document inside document, but without pre-defined structure. That's why this is one
+of fields, that has default value specified inside Mongoengine itself, and that's
+why is always (almost) created.
+
+The developer should understand that database keyword argument {attr}`default` is
+forwarded to form by default, but can be separately overwritten in form. This brings
+a lot of options for form field configuration.
+
+Also, should be additionally noted that database `Null` value in form is represented as
+empty string. Non-existing field is represented with form {attr}`default` for new
+forms (without instance inside) or with empty string for non-empty forms.
+
+Complicated? Probably. That's why this field was completely rewritten in version
+**2.0.0**. Check examples, and everything will be clear.
+
+### Form generation behaviour
+
+Our default form generation follow Mongoengine internals and will use database field
+default (empty dict) to populate to new form or to not filled field in existing form.
+
+In the same time, we are allowing extending of this behaviour, and not creating
+field in database, if default value provided as `None`. In this case, generated
+field for new form will be empty, without any pre-filled value.
+
+Same empty field will be displayed in case, when both {attr}`default=None` and
+{attr}`null=True` selected, during database form initialization. In this case form
+field will be empty, without any placeholder, but on save `null` object will be
+created in document.
+
+Also, we even support separated defaults for form field and database field, allowing
+any form+database behaviour.
+
+### Examples
+
+#### DictField with default empty dict value
+
+Will place `{}` to form for existing/new fields. This value is hardcodded in parent
+MongoEngine project.
+
+```python
+"""dict_demo.py"""
+from example_app.models import db
+
+
+class DictDemoModel(db.Document):
+    """Documentation example model."""
+
+    dict_field = db.DictField()
+```
+
+#### DictField with default `None` value, ignored by database
+
+Reminder: Such field is empty in form, and will not create anything in database if
+not filled.
+
+```python
+"""dict_demo.py"""
+from example_app.models import db
+
+
+class DictDemoModel(db.Document):
+    """Documentation example model."""
+
+    no_dict_field = db.DictField(default=None)
+```
+
+#### DictField with default `None` value, saved to database
+
+Reminder: Such field is empty in form, and will create `null` object in database if
+not filled.
+
+```python
+"""dict_demo.py"""
+from example_app.models import db
+
+
+class DictDemoModel(db.Document):
+    """Documentation example model."""
+
+    null_dict_field = db.DictField(default=None, null=True)
+```
+
+#### DictField with pre-defined default dict
+
+This value is pre-defined on database level. So behaviour of form and in-code
+creation of such objects will be the same - default dict will be saved to database,
+if nothing provided to form/instance. Form will be pre-filled with default dict.
+
+```python
+"""dict_demo.py"""
+from example_app.models import db
+
+
+def get_default_dict():
+    """Example of default dict specification."""
+    return {"alpha": 1, "text": "text", "float": 1.2}
+
+
+class DictDemoModel(db.Document):
+    """Documentation example model."""
+
+    dict_default = db.DictField(default=get_default_dict)
+```
+
+#### DictField with pre-defined value and no document object creation on `Null`
+
+This is a case when you do not want to create any record in database document, if
+user completely delete pre-filled value in new document form. Here we use different
+`null` and `default` values in form field generation and during database object
+generation.
+
+```python
+"""dict_demo.py"""
+from example_app.models import db
+
+
+def get_default_dict():
+    """Example of default dict specification."""
+    return {"alpha": 1, "text": "text", "float": 1.2}
+
+
+class DictDemoModel(db.Document):
+    """Documentation example model."""
+
+    no_dict_prefilled = db.DictField(
+        default=None,
+        null=False,
+        wtf_options={"default": get_default_dict, "null": True},
+    )
+```
+
+#### DictField with pre-defined default dict with `Null` fallback
+
+This is very rare case, when some default value is given, meaning that this
+value will be populated to the field, but if completely deleted, than `Null` will be
+saved in database.
+
+```python
+"""dict_demo.py"""
+from example_app.models import db
+
+
+def get_default_dict():
+    """Example of default dict specification."""
+    return {"alpha": 1, "text": "text", "float": 1.2}
+
+
+class DictDemoModel(db.Document):
+    """Documentation example model."""
+
+    null_dict_default = db.DictField(default=get_default_dict, null=True)
+```
 
 ## EmailField
 

example_app/app.py

@@ -5,6 +5,7 @@
 from example_app import views
 from example_app.boolean_demo import boolean_demo_view
 from example_app.dates_demo import dates_demo_view
+from example_app.dict_demo import dict_demo_view
 from example_app.models import db
 from example_app.numbers_demo import numbers_demo_view
 from example_app.strings_demo import strings_demo_view
@@ -52,6 +53,8 @@
 app.add_url_rule("/dates/<pk>/", view_func=dates_demo_view, methods=["GET", "POST"])
 app.add_url_rule("/bool", view_func=boolean_demo_view, methods=["GET", "POST"])
 app.add_url_rule("/bool/<pk>/", view_func=boolean_demo_view, methods=["GET", "POST"])
+app.add_url_rule("/dict", view_func=dict_demo_view, methods=["GET", "POST"])
+app.add_url_rule("/dict/<pk>/", view_func=dict_demo_view, methods=["GET", "POST"])
 
 if __name__ == "__main__":
     app.run(host="0.0.0.0", port=8000)

example_app/boolean_demo.py

@@ -1,7 +1,5 @@
 """Booleans fields demo model."""
 
-from flask import render_template, request
-
 from example_app.models import db
 
 
@@ -24,25 +22,8 @@ class BooleanDemoModel(db.Document):
 
 def boolean_demo_view(pk=None):
     """Return all fields demonstration."""
-    form = BooleanDemoForm()
-    obj = None
-    if pk:
-        obj = BooleanDemoModel.objects.get(pk=pk)
-        form = BooleanDemoForm(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 = BooleanDemoModel.objects.paginate(page=page_num, per_page=100)
-
-    return render_template(
-        "form_demo.html",
-        view=boolean_demo_view.__name__,
-        page=page,
-        form=form,
-        model=BooleanDemoModel,
+    from example_app.views import demo_view
+
+    return demo_view(
+        model=BooleanDemoModel, view_name=boolean_demo_view.__name__, pk=pk
     )

example_app/dates_demo.py

@@ -1,6 +1,5 @@
 """Date and DateTime fields demo model."""
 
-from flask import render_template, request
 from wtforms.fields import DateTimeField
 
 from example_app.models import db
@@ -28,25 +27,6 @@ class DateTimeModel(db.Document):
 
 def dates_demo_view(pk=None):
     """Return all fields demonstration."""
-    form = DateTimeDemoForm()
-    obj = None
-    if pk:
-        obj = DateTimeModel.objects.get(pk=pk)
-        form = DateTimeDemoForm(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 = DateTimeModel.objects.paginate(page=page_num, per_page=100)
-
-    return render_template(
-        "form_demo.html",
-        view=dates_demo_view.__name__,
-        page=page,
-        form=form,
-        model=DateTimeModel,
-    )
+    from example_app.views import demo_view
+
+    return demo_view(model=DateTimeModel, view_name=dates_demo_view.__name__, pk=pk)

example_app/dict_demo.py

@@ -0,0 +1,34 @@
+"""Dict fields demo model."""
+
+from example_app.models import db
+
+
+def get_default_dict():
+    """Example of default dict specification."""
+    return {"alpha": 1, "text": "text", "float": 1.2}
+
+
+class DictDemoModel(db.Document):
+    """Documentation example model."""
+
+    string = db.StringField(verbose_name="str")
+    dict_field = db.DictField()
+    no_dict_field = db.DictField(default=None)
+    null_dict_field = db.DictField(default=None, null=True)
+    dict_default = db.DictField(default=get_default_dict)
+    null_dict_default = db.DictField(default=get_default_dict, null=True)
+    no_dict_prefilled = db.DictField(
+        default=None,
+        null=False,
+        wtf_options={"default": get_default_dict, "null": True},
+    )
+
+
+DictDemoForm = DictDemoModel.to_wtf_form()
+
+
+def dict_demo_view(pk=None):
+    """Return all fields demonstration."""
+    from example_app.views import demo_view
+
+    return demo_view(model=DictDemoModel, view_name=dict_demo_view.__name__, pk=pk)

example_app/numbers_demo.py

@@ -2,8 +2,6 @@
 
 from decimal import Decimal
 
-from flask import render_template, request
-
 from example_app.models import db
 
 
@@ -26,25 +24,8 @@ class NumbersDemoModel(db.Document):
 
 def numbers_demo_view(pk=None):
     """Return all fields demonstration."""
-    form = NumbersDemoForm()
-    obj = None
-    if pk:
-        obj = NumbersDemoModel.objects.get(pk=pk)
-        form = NumbersDemoForm(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 = NumbersDemoModel.objects.paginate(page=page_num, per_page=100)
-
-    return render_template(
-        "form_demo.html",
-        view=numbers_demo_view.__name__,
-        page=page,
-        form=form,
-        model=NumbersDemoModel,
+    from example_app.views import demo_view
+
+    return demo_view(
+        model=NumbersDemoModel, view_name=numbers_demo_view.__name__, pk=pk
     )

example_app/strings_demo.py

@@ -1,8 +1,6 @@
 """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
 
@@ -32,25 +30,8 @@ class StringsDemoModel(db.Document):
 
 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(
-        "form_demo.html",
-        view=strings_demo_view.__name__,
-        page=page,
-        form=form,
-        model=StringsDemoModel,
+    from example_app.views import demo_view
+
+    return demo_view(
+        model=StringsDemoModel, view_name=strings_demo_view.__name__, pk=pk
     )

example_app/templates/layout.html

@@ -22,6 +22,7 @@
     <li><a href="{{ url_for("numbers_demo_view") }}">Numbers demo</a></li>
     <li><a href="{{ url_for("dates_demo_view") }}">DateTime demo</a></li>
     <li><a href="{{ url_for("boolean_demo_view") }}">Booleans demo</a></li>
+    <li><a href="{{ url_for("dict_demo_view") }}">Dict/Json demo</a></li>
   </ul>
 </nav>
 <div>