Merge pull request #504 from MongoEngine/datetime_fields

New model form generator: Support of ComplexDateTimeField, DateField, DateTimeField

Author: insspb

docs/forms.md

@@ -87,13 +87,169 @@ Not yet documented. Please help us with new pull request.
 
 Not yet documented. Please help us with new pull request.
 
+### ComplexDateTimeField
+
+- API: {class}`.db_fields.ComplexDateTimeField`
+- Default form field class: {class}`wtforms.fields.DateTimeLocalField`
+
+#### Form generation behaviour
+
+ComplexDateTimeField stores date and time information in database `string` format. This
+format allow precision up to microseconds dimension.
+
+Unfortunately, there is no HTML5 field, that allow so high precision. That's why, by
+default the generated field will use HTML5 `<input type="datetime-local">` with
+precision set to milliseconds.
+
+If you require concrete microseconds for edit purposes, please use
+{class}`wtforms.fields.DateTimeField` with correct format (see examples below).
+
+Field is easy adjustable, to use any other precision. Check examples and example app
+for more details.
+
+#### Examples
+
+dates_demo.py in example app contain basic non-requirement example. You can adjust
+it to any provided example for test purposes.
+
+##### ComplexDateTimeField with milliseconds precision
+
+```python
+"""dates_demo.py"""
+from example_app.models import db
+
+
+class DateTimeModel(db.Document):
+    """Documentation example model."""
+
+    complex_datetime = db.ComplexDateTimeField()
+```
+
+##### ComplexDateTimeField with seconds precision
+
+```python
+"""dates_demo.py"""
+from example_app.models import db
+
+
+class DateTimeModel(db.Document):
+    """Documentation example model."""
+
+    complex_datetime_sec = db.ComplexDateTimeField(
+        wtf_options={"render_kw": {"step": "1"}}
+    )
+```
+
+##### ComplexDateTimeField with microseconds precision (text)
+
+```python
+"""dates_demo.py"""
+from wtforms.fields import DateTimeField
+
+from example_app.models import db
+
+
+class DateTimeModel(db.Document):
+    """Documentation example model."""
+
+    complex_datetime_microseconds = db.ComplexDateTimeField(
+        wtf_field_class=DateTimeField, wtf_options={"format": "%Y-%m-%d %H:%M:%S.%f"}
+    )
+```
+
 ### DateField
 
-Not yet documented. Please help us with new pull request.
+- API: {class}`.db_fields.DateField`
+- Default form field class: {class}`wtforms.fields.DateField`
+
+#### Form generation behaviour
+
+DateField is one of the simplest fields in the forms generation process. By default,
+the field use {class}`wtforms.fields.DateField` WTForms class, representing a form
+input with standard HTML5 `<input type="date">`. No custom additional transformation
+done, during field generation. Field is fully controllable by [global transforms].
+
+#### Examples
+
+dates_demo.py in example app contain basic non-requirement example. You can adjust
+it to any provided example for test purposes.
+
+```python
+"""dates_demo.py"""
+from example_app.models import db
+
+
+class DateTimeModel(db.Document):
+    """Documentation example model."""
+
+    date = db.DateField()
+```
+
+##### Not limited DateField
+
+```python
+pass
+```
 
 ### DateTimeField
 
-Not yet documented. Please help us with new pull request.
+- API: {class}`.db_fields.DateTimeField`
+- Default form field class: {class}`wtforms.fields.DateTimeLocalField`
+
+#### Form generation behaviour
+
+DateTimeField stores date and time information in database `date` format. This
+format allow precision up to milliseconds dimension. By default, generated form will
+use HTML5 `<input type="datetime-local">` with precision set to seconds.
+
+Field is easy adjustable, to use any other precision. Check examples and example app
+for more details.
+
+It is possible to use {class}`wtforms.fields.DateTimeField` for text input behaviour.
+
+#### Examples
+
+dates_demo.py in example app contain basic non-requirement example. You can adjust
+it to any provided example for test purposes.
+
+##### DateTimeField with seconds precision
+
+```python
+"""dates_demo.py"""
+from example_app.models import db
+
+
+class DateTimeModel(db.Document):
+    """Documentation example model."""
+
+    datetime = db.DateTimeField()
+```
+
+##### DateTimeField without seconds
+
+```python
+"""dates_demo.py"""
+from example_app.models import db
+
+
+class DateTimeModel(db.Document):
+    """Documentation example model."""
+
+    datetime_no_sec = db.DateTimeField(wtf_options={"render_kw": {"step": "60"}})
+```
+
+##### DateTimeField with milliseconds precision
+
+```python
+"""dates_demo.py"""
+from example_app.models import db
+
+
+class DateTimeModel(db.Document):
+    """Documentation example model."""
+
+    datetime_ms = db.DateTimeField(wtf_options={"render_kw": {"step": "0.001"}})
+```
 
 ### DecimalField
 
@@ -533,10 +689,6 @@ class StringsDemoModel(db.Document):
 
 Not yet documented. Please help us with new pull request.
 
-### ComplexDateTimeField
-
-Not yet documented. Please help us with new pull request.
-
 ### DynamicField
 
 Not yet documented. Please help us with new pull request.

example_app/app.py

@@ -3,6 +3,7 @@
 from pymongo import monitoring
 
 from example_app import views
+from example_app.dates_demo import dates_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
@@ -42,14 +43,12 @@
 
 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"]
-)
-app.add_url_rule("/numbers_demo", view_func=numbers_demo_view, methods=["GET", "POST"])
-app.add_url_rule(
-    "/numbers_demo/<pk>/", view_func=numbers_demo_view, methods=["GET", "POST"]
-)
+app.add_url_rule("/strings", view_func=strings_demo_view, methods=["GET", "POST"])
+app.add_url_rule("/strings/<pk>/", view_func=strings_demo_view, methods=["GET", "POST"])
+app.add_url_rule("/numbers", view_func=numbers_demo_view, methods=["GET", "POST"])
+app.add_url_rule("/numbers/<pk>/", view_func=numbers_demo_view, methods=["GET", "POST"])
+app.add_url_rule("/dates", view_func=dates_demo_view, methods=["GET", "POST"])
+app.add_url_rule("/dates/<pk>/", view_func=dates_demo_view, methods=["GET", "POST"])
 
 if __name__ == "__main__":
     app.run(host="0.0.0.0", port=8000)

example_app/dates_demo.py

@@ -0,0 +1,52 @@
+"""Date and DateTime fields demo model."""
+
+from flask import render_template, request
+from wtforms.fields import DateTimeField
+
+from example_app.models import db
+
+
+class DateTimeModel(db.Document):
+    """Documentation example model."""
+
+    any_string = db.StringField()
+    date = db.DateField()
+    datetime = db.DateTimeField()
+    datetime_no_sec = db.DateTimeField(wtf_options={"render_kw": {"step": "60"}})
+    datetime_ms = db.DateTimeField(wtf_options={"render_kw": {"step": "0.001"}})
+    complex_datetime = db.ComplexDateTimeField()
+    complex_datetime_sec = db.ComplexDateTimeField(
+        wtf_options={"render_kw": {"step": "1"}}
+    )
+    complex_datetime_microseconds = db.ComplexDateTimeField(
+        wtf_field_class=DateTimeField, wtf_options={"format": "%Y-%m-%d %H:%M:%S.%f"}
+    )
+
+
+DateTimeDemoForm = DateTimeModel.to_wtf_form()
+
+
+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,
+    )

example_app/numbers_demo.py

@@ -42,5 +42,9 @@ def numbers_demo_view(pk=None):
     page = NumbersDemoModel.objects.paginate(page=page_num, per_page=100)
 
     return render_template(
-        "numbers_demo.html", page=page, form=form, model=NumbersDemoModel
+        "form_demo.html",
+        view=numbers_demo_view.__name__,
+        page=page,
+        form=form,
+        model=NumbersDemoModel,
     )

example_app/strings_demo.py

@@ -48,5 +48,9 @@ def strings_demo_view(pk=None):
     page = StringsDemoModel.objects.paginate(page=page_num, per_page=100)
 
     return render_template(
-        "strings_demo.html", page=page, form=form, model=StringsDemoModel
+        "form_demo.html",
+        view=strings_demo_view.__name__,
+        page=page,
+        form=form,
+        model=StringsDemoModel,
     )

example_app/templates/numbers_demo.html renamed to example_app/templates/form_demo.html

@@ -9,7 +9,7 @@
       <thead>
       <tr>
         {% for field in model._fields_ordered %}
-          <th>{{ model[field].name }}</th>
+          <th>{{ model[field].verbose_name or model[field].name}}</th>
         {% endfor %}
         <th>Edit</th>
       </tr>
@@ -20,14 +20,14 @@
           {% for field in page_object._fields_ordered %}
             <td>{{ page_object[field] }}</td>
           {% endfor %}
-          <td><a href="{{ url_for('numbers_demo_view', pk=page_object.pk) }}">edit</a></td>
+          <td><a href="{{ url_for(view, pk=page_object.pk) }}">edit</a></td>
         </tr>
       {% endfor %}
       </tbody>
     </table>
   </div>
   <div>
-    {{ render_navigation(page, "numbers_demo_view") }}
+    {{ render_navigation(page, view) }}
   </div>
   <div>
     <form method="POST">

example_app/templates/layout.html

@@ -20,6 +20,7 @@
     <li><a href="{{ url_for("pagination") }}">Pagination</a></li>
     <li><a href="{{ url_for("strings_demo_view") }}">Strings demo</a></li>
     <li><a href="{{ url_for("numbers_demo_view") }}">Numbers demo</a></li>
+    <li><a href="{{ url_for("dates_demo_view") }}">DateTime demo</a></li>
   </ul>
 </nav>
 <div>

example_app/templates/strings_demo.html

@@ -4,6 +4,7 @@
 from mongoengine.context_managers import switch_db
 
 from example_app import models
+from example_app.dates_demo import DateTimeModel
 from example_app.numbers_demo import NumbersDemoModel
 from example_app.strings_demo import StringsDemoModel
 
@@ -49,6 +50,7 @@ def delete_data():
     """Clear database."""
     with switch_db(models.Todo, "default"):
         models.Todo.objects().delete()
+        DateTimeModel.objects().delete()
         StringsDemoModel.objects().delete()
         NumbersDemoModel.objects().delete()
     with switch_db(models.Todo, "secondary"):